REST (Restful State Transfer) is an API design architecture used to implement web services. REST compliant web services allow the requesting systems to access and manipulate the textual representation of web resources by using a uniform and predefined set of stateless operations (GET, PUT, POST, DELETE etc.)
Why would someone want to use REST?
- HTTP Semantics
REST APIs are built on top of HTTP and take full advantage of core HTTP features such as HTTP request methods, HTTP response status codes and HTTP caching.
HTTP implements caching and REST implements HTTP. Hence, clients can use HTTP caching to avoid refetching commonly requested resources without including any specific logic. HTTP headers in response data provide information to the client on how to cache the returned data. This is important for performance, user experience and network data usage.
- Monitoring/Error Handling
HTTP provides specific failure codes to describe response error states. We check HTTP headers to get the status of the response. Depending on the HTTP status code (404, 500, 503 etc), we can tell what the error is and how to resolve it. This can be parsed and used to programmatically determine how an application responds to failed requests.
API analytics are easy to obtain for REST.
Why would someone NOT want to use REST?
- Slow Development
REST APIs are typically structured according to the views that are inside the application. Each specific view needs its specific endpoint. Hence, with every change in UI, there is a high risk that now more data is required than before. As a result, the backend needs to be adjusted to account for the new data needs. This kills productivity and development has to slow down until the endpoint is updated.
- Under-fetching/Multiple Round Trips
Underfetching means a specific endpoint doesn’t provide enough of the required information. The client has to make additional requests to fetch everything it needs.
Ex: An app needs to display an author along with the posts he/she has created and in turn get the comments on each of these posts. With REST, you would gather this data by hitting multiple endpoints.
Overfetching means a specific endpoint returns additional information that is not needed. REST requests always return the full set of data that is available for a certain resource. There is no way to limit the request to only retrieve a subset of data fields.
Ex: A screen needs to display the list of users only with their names. With REST, we would hit the users endpoint and the returned data might contain additional information about the user such as birthday, address etc. which is of no use.
As REST APIs evolve, you don’t want to break the clients that are already connected to your system while still needing to alter your API. This requires versioning and APIs are versioned as v1, v2, v3 etc. This leads to code redundancy and less maintainable code.
GraphQL is a query language for APIs that enables declarative data fetching in order to give client the power to specify exactly the data that is needed from the API. GraphQL operates over a single endpoint using HTTP.
Why would someone want to use GraphQL?
- Flexibility & Efficiency
Due to the flexible nature of GraphQL, changes on the client side can be made without any extra work on the server. Since you are only fetching the data that you require, you limit the amount of processing required.
- Insightful Analytics/Easy to evolve APIs
GraphQL allows you to have fine grained insights about the data that is requested on the backend. Since clients specify exactly what they need, it is possible to get a deep understanding of how the available data is being used. This can help in evolving an API and deprecating specific fields that are not requested by any clients anymore. With GraphQL you can do low level performance monitoring of the requests that are processed by your server.
- Schema & Type System
GraphQL uses its own type system to define the schema of an API with its syntax called Schema Definition language (SDL). This schema acts as a contract between the server and the client to define how a client can access the data. GraphQL schema provides type safety as it catches type errors early.
- Fast Development
GraphQL provides a smooth and fast development environment with its declarative and flexible nature.
- No Versioning
With GraphQL there is no need for versioning. We can add new fields and types to our GraphQL API without impacting existing queries. We can easily mark fields as deprecated and those fields will be excluded from the response.
Why would someone NOT want to use GraphQL?
- No HTTP Caching Mechanism
In GraphQL, client requests are all HTTP POSTs and completely bypass the standard HTTP caching mechanism. Hence, GraphQL client applications tend to use libraries to achieve caching. However this requires more work from the developers to get the full benefit of caching.
- Monitoring and Error Reporting
With GraphQL, the API always returns 200 OK status response even if there are errors. Hence, it is very difficult to handle and monitor different error scenarios. To determine if a specific request has failed, you have to extract the error information and determine the failure cause.
- Resource Attacks
GraphQL leads to complex security implications. A malicious actor can submit an expensive nested query to overload your server or database. If your server doesn’t have the right protection, you will be vulnerable to DDoS attacks.
- Schema Introspection
GraphQL provides schema introspection or informative error messages by default. Using this a bad actor can understand how to make requests against your API.
If your application requires a robust API, with caching and monitoring system, go with REST.
If your application requires flexibility, efficiency and if bandwidth usage matters, go with GraphQL.