Documenting GraphQL APIs vs REST

Recent studies show that the adoption of GraphQL is increasing, and it has a very wide global user base. When it comes to API documentation, many users may still be unfamiliar with GraphQL language but may have experience with REST API. It’s crucial to understand the commonalities and differences between what needs to be covered for GraphQL and REST API documentation. GraphQL and REST are different approaches to design APIs based on the ways they structure the data and on how the client requests the data. Both are not mutually exclusive, and they complement each other as GraphQL can act as a layer on top of REST.

Key takeaways

• GraphQL APIs is defined by single endpoint and not multiple end points like REST.
• In GraphQL, queries only return the requested fields. Fields can be defined in separate JSON or YAML files and imported into the schema. 
• While documenting GraphQL APIs, provide concise explanation for each type, fields, comments, their relationships, etc.
• Introspection queries allows you to query the entire schema. Technical writers can explain what introspection is and provide examples to developers to explore entire API schema.
• Document common error scenarios and how to handle them while handling errors in GraphQL. You may add the structure of error responses too for better clarity.