Practique consultas GraphQL con la API State of JavaScript

Aprender a crear API GraphQL puede resultar todo un desafío. ¡Pero puedes aprender a usar las API GraphQL en 10 minutos! Y resulta que tengo la API perfecta para eso: la nueva API GraphQL de JavaScript State of the VS-Code.

La encuesta sobre el estado de JavaScript es una encuesta anual del panorama de JavaScript. Lo hemos estado haciendo durante cuatro años y la edición más reciente llegó a más de 20.000 desarrolladores.

Siempre hemos confiado en Gatsby para construir nuestro sitio de exhibición, pero hasta este año, le estábamos suministrando nuestros datos a Gatsby en forma de archivos YAML estáticos generados a través de algún tipo de magia arcana conocida por los simples mortales como “ElasticSearch”.

Pero dado que Gatsby elimina todas las fuentes de datos que consume como GraphQL de todos modos, pensamos que también podríamos omitir al intermediario y alimentarlo con GraphQL directamente. Sí, lo sé, esta metáfora se vuelve cada vez más asquerosa y ya me arrepiento. Mi punto es: creamos una API GraphQL interna para nuestros datos y ahora la ponemos a disposición de todos para que usted también pueda explotar fácilmente nuestro conjunto de datos.

“Pero espera”, dices. “¡He pasado toda mi vida estudiando la hoja, lo que no me ha dejado tiempo para aprender GraphQL!” No te preocupes: ahí es donde entra este artículo.

¿Qué es GraphQL?

En esencia, GraphQL es una sintaxis que le permite especificar qué datos desea recibir de una API. Tenga en cuenta que dije API y no base de datos. A diferencia de SQL, una consulta GraphQL no va directamente a su base de datos, sino a su punto final API GraphQL que, a su vez, puede conectarse a una base de datos o cualquier otra fuente de datos.

La gran ventaja de GraphQL sobre paradigmas más antiguos como REST es que te permite pedir lo que quieres. Por ejemplo:

query {  user(id: "foo123") {    name  }}

Le daría un objeto de usuario con un solo namecampo. ¿También necesitas el correo electrónico? Solo haz:

query {  user(id: "foo123") {    name    email  }}

Como puede ver, el campo de usuario en este ejemplo admite un idargumento. Y ahora llegamos a la característica más interesante de GraphQL, el anidamiento:

query {  user(id: "foo123") {    name    email    posts {       title      body    }  }}

Aquí, decimos que queremos encontrar el archivo posts, y cargar su titlearchivo body. Lo bueno de GraphQL es que nuestra capa API puede hacer el trabajo de descubrir cómo recuperar esa información adicional en ese formato específico, ya que no estamos hablando directamente con la base de datos, incluso si no está almacenada en un formato anidado dentro de nuestra base de datos real. base de datos.

Sebastian Scholl hace un trabajo maravilloso al explicar GraphQL como si lo estuvieras conociendo por primera vez en una coctelería.

Presentamos GraphiQL

GraphiQL (tenga en cuenta la “i” allí) es el IDE GraphQL más común que existe y es la herramienta que usaremos para explorar el estado de la API de JavaScript. Puede iniciarlo ahora mismo en graphiql.stateofjs.com y se conectará automáticamente a nuestro punto final (que es api.stateofjs.com/graphql ). La interfaz de usuario consta de tres elementos principales: el panel Explorador, el Generador de consultas y los paneles de Resultados. Más adelante agregaremos los paneles de Documentos, pero mantengámoslo simple por ahora.

La pestaña Explorer es parte de una versión mejorada de GraphiQL desarrollada y mantenida por OneGraph . Muchas gracias a ellos por ayudarnos a integrarlo. Asegúrese de consultar su repositorio de ejemplo si desea implementar su propia instancia de GraphiQL.

No te preocupes, no te obligaré a escribir ningún código todavía. En su lugar, comencemos desde una consulta GraphQL existente, como la correspondiente a la experiencia del desarrollador con React durante los últimos cuatro años .

¿Recuerda que dije que estábamos usando GraphQL internamente para construir nuestro sitio? No solo estamos exponiendo la API, sino que también estamos exponiendo las consultas mismas. Haga clic en el pequeño botón “Exportar”, copie la consulta en la pestaña “GraphQL”, péguela dentro de la ventana del generador de consultas de GraphiQL y haga clic en el botón “Reproducir”.

Si todo salió según lo planeado, deberías ver tus datos aparecer en el panel de Resultados. Tomémonos un momento para analizar la consulta.

query react_experienceQuery {  survey(survey: js) {    tool(id: react) {      id      entity {        homepage        name        github {          url        }      }      experience {        allYears {          year          total          completion {            count            percentage          }          awarenessInterestSatisfaction {            awareness            interest            satisfaction          }          buckets {            id            count            percentage          }        }      }    }  }}

Primero viene la querypalabra clave que define el inicio de nuestra consulta GraphQL, junto con el nombre de la consulta react_experienceQuery. Los nombres de las consultas son opcionales en GraphQL, pero pueden resultar útiles para fines de depuración.

Luego tenemos nuestro primer campo, surveyque toma un surveyargumento. (También tenemos una encuesta sobre el estado de CSS, por lo que necesitábamos especificar la encuesta en cuestión). Luego tenemos un toolcampo que acepta un idargumento. Y todo lo que sigue está relacionado con los resultados de la API para esa herramienta específica. entityle brinda información sobre la herramienta específica seleccionada (por ejemplo, React) y experiencecontiene los datos estadísticos reales.

Ahora, en lugar de seguir repasando todos esos campos aquí, le enseñaré un pequeño truco: Command+ haga clic (o Control+ haga clic) en cualquiera de esos campos dentro de GraphiQL y aparecerá el panel de Documentos. Felicitaciones, acaba de presenciar otro de los ingeniosos trucos de GraphQL: ¡la autodocumentación! Puede escribir documentación directamente en su definición de API y GraphiQL, a su vez, la pondrá a disposición de los usuarios finales.

Cambiando variables

Let’s tweak things a bit: in the Query Builder, replace “react” with “vuejs” and you should notice another cool GraphQL thing: auto-completion. This is quite helpful to avoid making mistakes or to save time! Press “Play” again and you’ll get the same data, but for Vue this time.

Using the Explorer

We’ll now unlock one more GraphQL power tool: the Explorer. The Explorer is basically a tree of your entire API that not only lets you visualize its structure, but also build queries without writing a single line of code! So, let’s try recreating our React query using the explorer this time.

First, let’s open a new browser tab and load graphiql.stateofjs.com in it to start fresh. Click the survey node in the Explorer, and under it the tool node, click “Play.” The tool’s id field should be automatically added to the results and — by the way — this is a good time to change the default argument value (“typescript”) to “react.”

Next, let’s keep drilling down. If you add entity without any subfields, you should see a little squiggly red line underneath it letting you know you need to also specify at least one or more subfields. So, let’s add id, name and homepage at a minimum. Another useful trick: you can automatically tell GraphiQL to add all of a field’s subfields by option+control-clicking it in the Explorer.

Next up is experience. Keep adding fields and subfields until you get something that approaches the query you initially copied from the State of JavaScript site. Any item you select is instantly reflected inside the Query Builder panel. There you go, you just wrote your first GraphQL query!

Filtering data

You might have noticed a purple filters item under experience. This is actually they key reason why you’d want to use our GraphQL API as opposed to simply browsing our site: any aggregation provided by the API can be filtered by a number of factors, such as the respondent’s gender, company size, salary, or country.

Expand filters and select companySize and then eq and range_more_than_1000. You’ve just calculated React’s popularity among large companies! Select range_1 instead and you can now compare it with the same datapoint among freelancers and independent developers.

It’s important to note that GraphQL only defines very low-level primitives, such as fields and arguments, so these eq, in, nin, etc., filters are not part of GraphQL itself, but simply arguments we’ve defined ourselves when setting up the API. This can be a lot of work at first, but it does give you total control over how clients can query your API.

Conclusion

Hopefully you’ve seen that querying a GraphQL API isn’t that big a deal, especially with awesome tools like GraphiQL to help you do it. Now sure, actually integrating GraphQL data into a real-world app is another matter, but this is mostly due to the complexity of handling data transfers between client and server. The GraphQL part itself is actually quite easy!

Whether you’re hoping to get started with GraphQL or just learn enough to query our data and come up with some amazing new insights, I hope this guide will have proven useful!

And if you’re interested in taking part in our next survey (which should be the State of CSS 2020) then be sure to sign up for our mailing list so you can be notified when we launch it.

State of JavaScript API Reference

You can find more info about the API (including links to the actual endpoint and the GitHub repo) at api.stateofjs.com.

Here’s a quick glossary of the terms used inside the State of JS API.

Top-Level Fields

• Demographics: Regroups all demographics info such as gender, company size, salary, etc.
• Entity: Gives access to more info about a specific “entity” (library, framework, programming language, etc.).
• Feature: Usage data for a specific JavaScript or CSS feature.
• Features: Same, but across a range of features.
• Matrices: Gives access to the data used to populate our cross-referential heatmaps.
• Opinion: Opinion data for a specific question (e.g. “Do you think JavaScript is moving in the right direction?”).
• OtherTools: Data for the “other tools” section (text editors, browsers, bundlers, etc.).
• Resources: Data for the “resources” section (sites, blogs, podcasts, etc.).
• Tool: Experience data for a specific tool (library, framework, etc.).
• Tools: Same, but across a range of tools.
• ToolsRankings: Rankings (awareness, interest, satisfaction) across a range of tools.

Common Fields

• Completion: Which proportion of survey respondents answered any given question.
• Buckets: The array containing the actual data.
• Year/allYears: Whether to get the data for a specific survey year; or an array containing all years.