Power tools for your API
Sashko Stubailo
For a long time now, people have been excited about the potential of APIs and “mashup” apps. At every hackathon, you see tons of companies lining up to give out prizes for using their API to build something cool. There are many services these days that promise to make building, using, and documenting APIs easy and fun, to unlock the value in your organization’s data. There are also many conferences, websites, and blogs about API development.
But even though we’ve spent so much time improving API tools, we haven’t quite fulfilled the ultimate promise: self-documenting, semantic, easily consumable data.
You can’t yet dream up an app and start building it without searching through a ton of documentation, specialized packages and SDKs, and maybe even building an extra API server on top of your APIs because those APIs aren’t really what you needed in the first place.
What if there were a uniform and descriptive API language that all of your tools could understand and integrate seamlessly into your design and development workflow? That is the destiny of GraphQL.
You can think of GraphQL like REST 2.0 — it’s a nested data fetching language that works on top of a strongly-typed self-documenting description of all of the data available in your system. Given that every GraphQL API must fit these parameters, we can take advantage of that information to build some really next-level developer tools. We already talked about mocking your backend data with one line of code — what else could we do?
Try it today: Validate queries with ESLint
Think about the API you’re using in your React or Angular app right now. Do you know the answer to any of the following questions?
- Which parts of your many frontend apps are using certain endpoints?
- Are there any parts of your frontend code that have typos when accessing different fields on your API responses?
- If you made any changes to your API, are there any of your frontend apps that you forgot to update to the new format?
Perhaps if you have the most principled code review and documentation in the world, then you know. But for most of us, it’s a mystery — if you have tons of places that are accessing your backend data, making any changes to that backend can be a gamble, and it’s not clear when you’re writing your frontend code if you made any typos.
With GraphQL, you can know, because you can check what data your frontend is requesting statically by inspecting the queries in your code.
As an example, I put together an ESLint plugin for GraphQL, which validates your queries against a backend schema. As you type into your editor, it is constantly checking that the data you’re trying to fetch is actually valid — no more typos in endpoint parameters or field names!
If you’re already using GraphQL in your JavaScript app, try it now:apollostack/eslint-plugin-graphqleslint-plugin-graphql — Check your GraphQL query strings against a schema.github.com
Having a tool like this effectively reduces the gap between the client and server components of your app, without coupling them. Since every GraphQL API server can easily export a schema — basically a description of all of the types of data that can be fetched from that server — you can write your server in any language you want, but use the same tools on the frontend to validate the queries.
Better yet, GraphQL includes deprecation as a first-class feature, so you can slowly phase out usage of a certain type or field until you are sure no client is using it anymore.
This is just a simple example of the kinds of tools you can build on top of GraphQL. But let’s not stop there, and dream bigger!
Wish list of GraphQL developer tools
There are so many tools that could be built for GraphQL that couldn’t really be built on top of any other system.
In-editor query autocompletion
The linter plugin above already tells you when you’ve made a typo in one of your queries, right inside your editor. What if we could actually suggest different fields directly in there?
You might never need to look up your API documentation again!
UI design with real data
James Baxley hooked me up with an idea this week that blew my mind. Many designers use tools like Sketch to prepare UI designs and mockups, and Sketch plugins can merge generated data with the designs. What if you could just load up an arbitrary query, and get either mocked data from your prepared mocks or real data from your production server to test out your design?
You could do a similar thing with Arunoda’s React Storybook — there could be a plugin that lets you simply write a GraphQL query that matches the shape of the arguments for your components, and gives you the data you need.
Some more ideas
If you just sit down for a minute and think, I’m sure you can up with a ton more stuff:
- Guard against unused data: When you have a REST API, the backend will often return fields that you don’t use on the frontend. But with GraphQL, you get to specify exactly the fields you need, so shouldn’t your editor warn you when you are fetching a field you don’t actually access?
- Typed result objects: If you’re programming in a typed language, like Flow, TypeScript, Java, or Swift, your tooling should be able to give you a typed result object from your query. I suspect this is exactly what Facebook is doing internally; after all, GraphQL was initially developed for their mobile apps!
- Build your UI without running your backend: Since your schema completely defines what types of data you might get out of your API, simple mocking functionality would allow you to work on your app’s UI even before the backend is ready.
- Generate test fixtures as you need them: Like we did for the ESLint plugin tests, you can generate a schema without defining any data loading logic at all, and use that as a fixture for your tests.
How do we get it done?
With all of the potential of GraphQL, it’s clear that we are in the very early days of this ecosystem. I suspect we’ve barely discovered 5% of what is possible, and as we as a community build more and more of these tools it’ll become clear just how much of a quantum leap GraphQL really is. On the Apollo team, we’re dedicated to pushing the very limits of that potential.
One of the things that’s going to be really valuable for development tools specifically is having a standard way to introspect information about one’s GraphQL schema, including types, queries, mutations, and metadata.
I’ve started a repository called “graphqlrc” where we can talk about the various needs of such a system, and how it could be implemented. I’ve called it “graphqlrc” to align with a venerable history of config files, but it could be anything — a file, worker service, or something else. If you’re as hyped as I am about the possibilities for GraphQL developer tools, let’s talk there:
https://github.com/apollostack/graphqlrc
Also, if you’re interested in GraphQL, APIs, or data loading in general, follow our Building Apollo publication here on Medium!
