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.
Based on research by our user experience group, here’s what we found out about the developers who use Contentful.
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.
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:
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:
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:
Schema stitching allows you to combine two GraphQL APIs into one. Use cases can include:
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.