REST, SOAP, or GraphQL

Which API style to use in your company and why?

Nowadays, APIs (Application Programming Interfaces) drive pretty much all software. You use platform APIs to access features your app’s target platform provides. You use third-party APIs to connect with different tools, products, and services. Lastly, you develop your own APIs to accelerate internal development and provide programmable access to your product for other users.

In this article, I’d like to compare three leading API styles - REST, SOAP, and GraphQL - to see how they stack up against each other and when should you choose which?

API styles

APIs can be designed in various ways. Their architecture can vary depending on their use case, required scalability, data structure, and so on. That’s why most companies will have multiple APIs built with different technologies and use-cases in mind.

With that said, how to structure and develop your API is something you should think about ahead of time - picking the right API style for the job.

REST

REST is the most widely-used and well-known API style. Its name is an acronym standing for REpresentational State Transfer, which, in broad terms, describes how REST works.

In REST API, upon an HTTP request, the representation of the resource’s state is transferred to the client. The data can be delivered in one of the HTTP-supported formats, like JSON, along with metadata, cookies, and more in HTTP parameters and headers.

Thanks to its heavy reliance on HTTP (primary transfer protocol on the Web), ease of use, and versatile rules, REST has become the dominant API style - especially on the Web.

SOAP

After REST, SOAP (formerly an acronym for Simple Object Access Protocol, now just SOAP) is likely the 2nd most popular API style.

Although SOAP relies primarily on HTTP, it’s transfer-protocol-independent, meaning you aren’t limited to just HTTP, unlike with REST. With that said, SOAP puts more strict requirements on the data format, mandating it to be XML. It’s also more standardized, having a strict messaging structure and encoding rules.

SOAP’s use of XML, although possibly slowing down the API and generating unnecessarily complex responses, can provide more detail compared to, e.g., REST with JSON. There’s also built-in error handling outputting detailed info in XML format, with standardized error codes.

Thanks to all the above features and other advantages like support for various Web Service (WS*) standards, SOAP is well-suited for large, distributed environments.

GraphQL

Unlike REST or SOAP, GraphQL is not strictly a style or protocol but a query language for APIs. It was created by Facebook and is now an open-source software.

Instead of sending requests to several HTTP endpoints, with GraphQL, you can send a single request containing your GraphQL query to a single endpoint. The query lets you precisely specify what data you require. This approach is more efficient and more flexible.

The GraphQL server works on a pre-defined schema that determines which queries are allowed, what types of data can be retrieved, and how they’re related. Incoming queries are validated against the schema, eliminating the possibility of requesting the wrong data.

Overall, GraphQL puts development experience and client-side at the forefront. This can come at the cost of server-side, which is often more complex to implement than with, e.g., REST.

When and which to use?

Knowing the different characteristics of the API styles above, you should now be able to pick the one that suits your needs. If that can help, here are some further recommendations.

If you’ve already used REST and it fits your needs well, you can as well stick with it. REST is also a good choice for everyone new to API design or whose API isn’t too nested or very complicated.

If you need highly-detailed responses and don’t want to handle all the errors by hand, SOAP is here for you. Earlier mentioned, enterprise-scale distributed systems are also good candidates for SOAP.

Lastly, if you’re willing to put a bit more time into your API development, and would see a benefit in precise queries, give GraphQL a try. It can be beneficial when working with complex, nested data structures or developing a highly-interactive frontend.

Other API styles

It’s worth noting that REST, SOAP, and GraphQL aren’t all the options you have for API design. There’s also Flacor (similar to GraphQL) and various implementations of Remote Procedure Call (RPC) architecture that are fast and great for distributed systems (just like SOAP) - the primary one being gRPC.

I encourage you to look at all the API styles to find the one that best suits your needs.

Conclusion

As you can see, there are many API styles. The tremendous amount of available options lets you create the API you want. Whether you’re developing distributed systems, working with deeply-nested data structures, or simply exposing your product’s functionalities to clients, there’s an API style that will match your needs.