REST, SOAP, GraphQL — Gesundheit!
Stepping into modern API development and infrastructure can be tough with so many acronyms running around. For the uninitiated, it can be difficult to tell different API formats and specifications from one another, know their background, and figure out if they should use them.
There are a few major formats you should know if you work in APIs. In today’s article we’re going to walk through three of the heavy hitters: REST, SOAP, and GraphQL and break down their differences, positives, and negatives.
REST
REST stands for Representational State Transfer. RESTful APIs give a client access to a representation of the state of a desired resource. When called, the server will transfer the representation to the client.
Calling the Twitter API to fetch a list of tweets (the resource) gives us the state of those tweets — users, time, location, etc. Often times the representation returned to the client is a JSON payload, but it can also take on different formats such as XML or HTML.
In order to make a request the server needs two things from the client: an endpoint, and a an operation. Endpoints serve as an identifier for the desired resource- the URL(Uniform Resource Locator!) of where to find it. Operations takes the shape of an HTTP method like GET, PUT, POST, or DELETE.
Most of what we call “RESTful APIs” are actually just “HTTP interfaces” as they don’t fully meet the standards for REST architecture. When we say rest in industry, it’s often a colloquialism for a web API with an HTTP interface.
SOAP
SOAP stands for Simple Object Access Protocol. SOAP focuses on inducing three key characteristics: extensibility, neutrality (not protocol specific), and independence (not architecture specific). SOAP requires transmitting data in XML, but as it is protocol agnostic it can use HTTP, SMTP, or anything else to negotiate and send messages requests. A SOAP request must always contain an envelope which identifies the XML as a SOAP message, and a body to contain call and response information. It can optionally contain headers and faults (used to describe errors). Here’s what a basic SOAP request looks like, :
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hs="http://www.holidaywebservice.com/HolidayService_v2/"><soapenv:Body><hs:GetHolidaysAvailable><hs:countryCode>UnitedStates</hs:countryCode></hs:GetHolidaysAvailable></soapenv:Body></soapenv:Envelope>
SOAP vs REST
On paper the key difference between REST and SOAP are the things they want to access. REST is ideal for fetching data. REST is often used when we expose public or partner APIs over the internet. It’s ideal for this purpose as it gives isolated and controlled access to named resources. In contrast, SOAP surfaces actual application logic through a different set of interfaces, it’s ideal for performing operations.
However, in reality the majority of use-cases could achieve the same results by leveraging either SOAP or REST. They each have slightly different configurations, but those don’t even differ too wildly from one another. Postman is a REST client but it can actually send requests in SOAP using XML tagging.
SOAP is technically the older, “legacy” API protocol (created by grandaddy Microsoft itself) — but REST isn’t the new kid on the block anymore. REST dramatically simplified interface with web services by using HTTP and its wide industry adoption shows that we haven’t forgotten.
GraphQL
Most of us have been creating and using REST APIs for a long time now. In the past few years people started talking about GraphQL as “Rest 2.0.” What’s with all the excitement, how is GraphQL even different than rest?
GraphQL was created by Facebook back in 2012 to support their mobile application infrastructure and then open sourced in 2015. It is a data fetching specification that also functions as an API query language (GraphQL).
Postman intends to fully support GraphQL, and we have it listed as an upcoming feature on our Trello board, which lists all of our upcoming functionality. Rodrigo Muñoz of Facebook gave a great talk on GraphQL Live Queries at Postcon 2018 which you can checkout here.
Though REST is an “architecture” and GraphQL is a “specification”, both tools are used to build and interact with APIs. GraphQL is not bound by any specific protocol, but it can also utilize HTTP like REST. Here’s an example of a GraphQL call sent via Postman:
GraphQL vs. REST
This subject is deep enough to write books about, but we’re going to go over the bullet points here. If you want a deeper dive I encourage checking out Phil Sturgeon’s series here.
Data fetching
Data fetching is often called out as the biggest improvement of GraphQL over REST. In a normal REST API, retrieving data from a server may require hitting more than one endpoint with requests. GraphQL reduces points of access to data on the server to a single endpoint. Because of this one request is enough to get both our resource as well as related resources.
Over/Under Fetching
REST requests often lead to over or under retrieval of information because endpoints return fixed data structures. The majority of the time, we are receiving a large payload when we only ever needed to query a single field — so all that extra information went to waste. We also might not see the information we want on our first REST request, and thus are forced to make more calls due to underfetching.
GraphQL doesn’t suffer from this problem as a query language. We can design queries to include exactly the information required. See the following GraphQL query that gets only the body of a tweet (No, Twitter doesn’t have a GraphQL API):
{
tweet{
body
}
}
{
"data": {
"tweet": {
"body": "Go Postman"
}
}
}
Error Handling
REST piggybacks on HTTP in order to deal with its error checking. . The returned HTTP status code ( 404, 503, 500 etc) conveys the error (i.e. 404 Not Found) and gives us a decent idea of how to fix it. GraphQL on HTTP gets a 200 OK response status, regardless of actual outcome. In the event of an error while running a GraphQL query, the error message is sent back to the client alongside the response, like so:
Caching
REST uses HTTP, which has built in caching. As a result the client can use the cache to avoid fetching the same thing twice. GraphQL, on the other hand, doesn’t have any caching baked into it. This means clients have to cache on their end.
Versioning
When working with REST APIs, we see frequent versioning — sometimes the field you are trying to fetch only exists in GenericAPI v2, and was deprecated in v3. Versioning makes the code on both sides of an API less maintainable. GraphQL APIs are able to be modified with new fields or types with no impact to existing queries. Fields can even be marked deprecated to exclude them from server responses. Take that GenericAPI v3!
SOAP vs GraphQL
GraphQL can be said to combine the strengths of both SOAP and REST. GraphQL and SOAP both use only a single endpoint to access data.However, GraphQL is more lightweight(smaller payloads)and doesn’t put as much strain on networks. Both formats are also strongly typed: we have to declare data types (Integer, String, Date, etc.)when using them; which causes less friction between services. One thing both formats lack is built in caching, requiring the use of other tools to augment them.
Which Do I Choose?
When considering what protocol is right for you consider what clients you will be supporting and how flexible you need to be.
- REST and JSON continues to be the starting stage for most new APIs as they are less heavy on bandwidth and more easily understood by developers who build or consume them. As a result, REST remains the go-to technology for most public APIs.
- SOAP still has use in certain situations, but is largely overshadowed as the veteran of the industry.
- GraphQL solved a lot of REST’s problems, and boasts a ton of other interesting features.
No API format is a silver bullet, they all have their strengths and weaknesses. Deciding on the one to use, as always, depends on the need.
