GraphQL and optimizing for developer experience

20190104 graphql agile organizations

Developer Experience (DX) is a field within user experience that describes the experience developers have when they use a product. It matters in the same way that User Experience (UX) matters. When users are happy, they'll continue to use your product and tell their communities about it too.

The functionality and power of our APIs, and our GraphQL project, are big reasons why developers love the Contentful DX. And it's something we've worked hard on to improve. There are too many companies who treat APIs as an afterthought or tack-on to their product.

All about developers

Based on research by our user experience group, here’s what we found out about the developers who use Contentful.

  • They move very quickly and have a high capability for learning
  • They have their own way of doing things. They’re opinionated and don’t like to deviate from their existing workflow and set up
  • Velocity matters. Developers like tools that let them code as quickly as possible without distractions or obstacles
  • Going hand in hand with the above, they also dislike redundancies

While we stand behind standards being built by others, sometimes Contentful does things differently. For instance, schemas would traditionally be fixed but our content models require dynamic schemas. Whenever possible we go with the standard but sometimes, we can do better. In the journey of our GraphQL project, we also explored use cases to discover what developers wanted to do and why.

How do we handle the developer experience?

When we look at the developer experience, it means looking at what developers expect. While they might not be looking for one-click solutions, a solution that feels natural and intuitive is important. Being intuitive means, for instance, being able to go into an API endpoint, and understand what the rest of the API looks like based on a first look.

Developers expect consistency; things should succeed and fail in predictable ways. We had our API return similar data to different queries so it’s easier to parse. When it succeeds, you’ll get a JSON output and you can parse easily. While in failure, we have errors that are clear and provide information so developers can figure out what the problem is quickly. We don’t want failures to occur blindly. As a result of our GraphQL coming out of alpha, we started providing a lot more information when it came to errors.

To cater to better DX, we’ve carried out initiatives such as:

  • Providing many SDK and tools available on our website and Contentful Labs
  • Enabling UI extensions and other projects, put together by our extensibility team, that allow you to extend the Contentful product and interface. Even if we haven’t built the feature you need, we give you the hooks to build it yourself.
  • Putting a lot of effort into documentation and developer relations. We’re constantly at the biggest development conferences all around the world and conduct many talks on how to use Contentful.For instance, we had a team of 10-15 people from different departments at this year’s GraphQL EU conferences engaging with the community of stakeholders, which was important considering how new and small the GraphQL community currently is.
  • Contentful’s blog also provides information on a broad scope of topics, notably how to do different things with Contentful using a variety of languages.

Building Developer Empathy

What we learned during this process is that we needed to build our developers' empathy with their customers, who are other developers. Here’s what we did:

  • Invite, include, and encourage collaboration by bringing them into research meetings so they hear what customers (developers) are saying
  • Bring feedback into the space of developers (i.e., team rooms) when we generate new ideas and work on exciting projects
  • Keep the conversation rolling and deliver work based on research that was presented to developers (customers)

Role of GraphQL

GraphQL is exceptionally conducive to providing a superior developer experience. As a descriptive query language for APIs, GraphQL can be written in any language you want as long as it delivers the payload as expected (it does have a standard distribution written in JavaScript). In essence, GraphQL is paving the road to more agile organizations and we at Contentful are supporting that movement by focusing on it.

GraphQL is able to deliver compact, customized responses for fields in the same order they were requested. This is unlike REST which returns everything it knows to you unless you specifically filter for information, assuming the developers have implemented filtering logic. GraphQL delivers smaller responses than REST, which improves page load times which is important for mobile. It’s also easier to parse, since it is returned in JSON in a structure identical to the query, and this improves developer velocity.

Another appeal of GraphQL is that it’s transport agnostic (generally done over HTTPS), serialization format agnostic (generally happens in JSON but doesn’t have to), and data source agnostic. As a result, you can build any kind of API based on that. Resolvers, what ties the schema back to your data source, can be written in any language and connect to any data source.

GraphQL does not dictate schema. You’re able to build a schema any way you want. It includes a Schema Definition Language, which is broken down into Types and Fields. In addition, GraphQL schemas are strongly typed, so you’ll always know what to expect. For further reading about schemas, read our article on abstract syntax trees (AST). ASTs serve the underlying foundation to dealing with schema definitions and parsing GraphQL queries. This strongly typed schema enables introspection and makes GraphQL fully self-documenting.

Introspection allows the user to see the entire GraphQL schema. Sending in a request for types and their objects will return everything one needs to know to perform queries on the data presented by the API. This allows a developer to write queries without any other API documentation. It also enables tools such as:

  • GraphiQL that support writing GraphQL queries for any GraphQL API
  • Prisma that simplifies build GraphQL servers providing access to database schemas without the need for a more traditional object-relational mapping (ORM) tool.

Schema stitching allows you to combine two GraphQL APIs into one. Use cases can include:

  • Microservices - If you have many microservice GraphQL APIs that do different things, you can stitch those together and have one single API. This lets you work with mutations and queries across many different microservices without having to individually address each microservice.
  • Databases - Similarly, you can attach a GraphQL API to an existing database. If you have a MySQL or Postgres database, you can put a Prisma client in front of it and stitch the schema that comes out of it with other schemas to have a single contiguous one.
  • Other APIs - You can also stitch your own GraphQL schema together with a public GraphQL API and integrate their data into one contiguous schema.

What Contentful does with its GraphQL API

Normally schemas are predefined and rigid. Because of Contentful's dynamic content models, schemas vary based on the content model structure at any given time. Because of this, we generate the schema at request time. However, we’ve worked hard on the implementation of dynamic schema generation for changing data models, and you can read more on this fresh approach and how it works to your benefit.

GraphQL is a query language for APIs that allows customized, compact queries that return small responses, that in turn eliminate unnecessary response data and makes applications faster. It also reduces the need for response parsing, which increases developer velocity and makes developers happy.

For Contentful, it makes everything even easier to use and doesn’t require building SDKs for every language we support in order to get data out of REST. If you’re interested in learning more, we also recently introduced GQLi, a GraphQL consumer domain-specific language that allows you to write GraphQL queries in native Ruby.

Blog posts in your inbox

Subscribe to receive most important updates. We send emails once a month.