February 7, 2020
TABLE OF CONTENTS
API design is crucial because it gives structure to how applications interact with each other. Given cross-functional teams and applications, development time is drastically reduced when there is a clear and intuitive way to access needed data. API development often follows two popular approaches: REST and GraphQL.
Traditionally, APIs have been built following REST. REST is an architectural principle built on two key ideas: the separation of client and server, and stateless information transfer. In a REST API, the client has all the information it needs to make server requests. It is also platform and language agnostic. This makes the client portable and flexible. A RESTful API uses standard HTTP requests (GET, POST, PUT, DELETE) to request information from a server. Because of this, REST APIs follow a uniform format and are easily understood across applications and services.
The uniformity and structure of REST does create some inflexibility. Each endpoint in a REST API corresponds to a single HTTP request for a particular resource. This makes interacting with specific pieces of data easy. However, when data is needed across multiple API endpoints, retrieval becomes cumbersome and resource-intensive. Furthermore, as the complexity of the data grows, REST APIs can become convoluted.
Imagine a simple REST API for a content website. The endpoints are simple initially, but the complexity grows fast.
Now we can see endpoints becoming exceedingly long and unintuitive. With REST, these kinds of endpoints occur more frequently. As the application grows, the API can become very complicated.
Another downside to a REST API is over-fetching and under-fetching of data. The server can send more or less data than needed, creating extra load on the application. Solving this issue by creating very specific APIs leads to more endpoints in the long run, and maintainability becomes difficult.
When documenting APIs using a tool like Swagger, a REST API can be challenging since endpoints do not have to be strongly typed. It is not easy to specify the data and integrity of a API endpoint that does not have strict requirements. Furthermore, API versioning can prove tough. In a large application, different environments could run different versions of the API that return different sets of data. More API versions equate to more endpoints, and more code to maintain in the long term.
GraphQL has become popular in recent years as another way to construct APIs. So, what is GraphQL? GraphQL is a query language that a developer uses to write a query to interact with the API. Even a complicated query completes itself in only *one *HTTP request. This single query contains the sought after data requirements, and the API sends back a JSON response that fulfills ALL the specifications.
A GraphQL schema defines the client-server data contract and what is possible to query. Because of this defined schema, teams can work relatively independently of each other. Changes to this schema, though infrequent, are generally easier than updating or adding endpoints in a REST API. An important note is that in GraphQL, the query will be what is changing, while the GraphQL schema that defines the data often remains the same.
Our same complex endpoint in a REST API would instead have a GraphQL query like the following:
A single query gives only the necessary data. If you want the query to return additional information, simply append it to the query. Thus, additional development cycles are not spent spinning up custom API endpoints. This causes a GraphQL query to typically be *faster *than REST, because the specificity of the query means you get back only what you need.
Furthermore, GraphQL is strongly typed, leading to consistent and accurate documentation. It is also schema-extending. Therefore, if business requirements change, modifying the schema does not break dependent code. GraphQL also deprecates fields that are no longer used, making versioning trivial.
Using GraphQL vs REST does have a few key downsides.
Can your business benefit from GraphQL? See our checklist to help make that determination.
When deciding how to design an API, consider the kinds of data the application will need to access. Will the requirements remain fairly stable over time and consist of simple resource retrieval? If so, a REST API provides uniformity and a modular structure that allows for easy data interaction. On the contrary, GraphQL is a query language that gives you the flexibility to work with a changing list of business requirements. GraphQL is also easily scalable for more complex data sets as a GraphQL query uses a single request model.
While GraphQL APIs have surged in popularity and have many benefits, REST APIs have greater market traction due to their longevity, familiarity, and seamless fit with a microservice architecture. GraphQL is still considered a more “immature” technology that will be refined over time, and will likely not replace REST altogether.
Meet our Experts
Amogh is an engineering consultant with experience in full-stack development and building enterprise scale web applications. He primarily works with Typescript on the front end with ReactJS, and on the backend with NodeJS. He has experience working for clients ranging from mid-sized insurance and fintech companies, to small startups.
Sergio Villarreal has more than 15 years of experience in software development and technology consulting in addition to expertise in desktop, web, mobile, and cloud development end-to-end solutions. Some of the industries he's worked in are banking, oil & gas, and energy, among others. Since 2015, Sergio has focused on cloud architecture with an interest in ML and AI. Outside of work, he enjoys exploring nature with his wife and little boy.
You're doing big things, and big things come with big challenges. We're here to help.