DEV Community 👩‍💻👨‍💻

Cover image for A Guide to the Most Popular Types of APIs: REST, SOAP, GraphQL, and gRPC
Pragati Verma
Pragati Verma

Posted on

A Guide to the Most Popular Types of APIs: REST, SOAP, GraphQL, and gRPC

APIs are the most important component of the modern-day software development process, helping applications and services communicate and transfer crucial information.

However, with the advancements in the field, now there are various choices to go with: REST, SOAP, GraphQL, or gRPC. That means whether you are an application architect or a backend developer, it’s essential that you understand which APIs are the best suited to particular applications.

Each API type has its unique architecture, which evolved in response to the needs of the time. And, as technology has evolved and our relationship with technology has altered, we've seen APIs arise to cover new gaps and serve new uses.

In this article, we’ll look at how SOAP, REST, GraphQL, and gRPC APIs compare to each other to give you a sense of their pros and cons, common use cases, and other considerations when you’re choosing the best one for your needs.

REST APIs

REpresentational State Transfer (REST) is a software architectural style for developing APIs to provide a simple, uniform interface. These can be used to make data, content, algorithms, media, and other digital resources accessible via web URLs, allowing them to be consumed via the web, mobile, and device applications. They allow data exchange in simple formats such as JSON and XML.

REST APIs adhere to the following six specific architectural constraints:

  1. A uniform interface
  2. Completely stateless
  3. Native caching
  4. Client-server architecture
  5. A layered system
  6. The ability to provide executable code to the client

Here’s an example of a REST API message:

{
  "car": {
    "vin": "KNDJT2A23A7703818",
    "make": "kia",
    "model": "soul",
    "year": 2010,
    "links": {
      "service": "/cars/KNDJT2A23A7703818/service",
      "sell": "/cars/KNDJT2A23A7703818/sell",
      "clean": "/cars/KNDJT2A23A7703818/sell"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Pros

  • REST APIs are based on the HTTP protocol, which means they are format-agnostic, allowing you to utilize XML, JSON, HTML, and other formats. This makes REST APIs quick and lightweight, which is essential for mobile app development, internet of things devices, and other applications.

  • REST APIs can be discovered easily from the URL, thus, they are very easy for the developers to test and integrate with their applications.

  • REST APIs are stateless, hence, they are very flexible to use as well as highly scalable as per the use case.

  • These APIs can be developed in Python, JavaScript (Node.js), Ruby, C#, and a variety of other languages, making them more accessible to most developers.

Cons

  • One downside of RESTful APIs is the loss of the ability to maintain a state, such as within sessions. It may also be more challenging to utilize for novice developers.

  • REST does impose any security thus, it is appropriate for public URLs, but it is not good for confidential data exchange between the client and the server.

  • There is no binding contract on the structure of communication. As a result, when it comes to execution, there is a lot of back and forth, which can lead to unnecessary frustration and bottlenecks.

You can use API Tester to create and send your first REST API request and see for yourself how it works.

SOAP APIs

The Simple Object Access Protocol (SOAP) is a protocol for sharing information encoded in Extensible Markup Language (XML) between a client and an Internet-based operation or service. It can be used with various transport protocols such as HTTP, FTP, SMTP, etc.

SOAP is commonly used in conjunction with the Web Service Description Language (WSDL). The importance of WSDL is that it allows developers and machines to analyze a web service that supports SOAP to learn about the nuances of information exchange over the network. Furthermore, the WSDL explains how to format the SOAP request and answer messages supported by the provided service.

SOAP is utilized for enterprise-level web services requiring high security and complicated transactions. SOAP is frequently used in APIs for financial services, payment gateways, CRM software, identity management, and telephony services.

A SOAP message has a hierarchical structure, with the <soap:Envelope> as the root element. Three child elements can be added to the root element. These are the child elements <soap:Header>, <soap:Body>, and <soap:Fault>.

Here’s an example of a SOAP message:

POST /Quotation HTTP/1.0
Host: www.xyz.org
Content-Type: text/xml; charset = utf-8
Content-Length: nnn

<?xml version = "1.0"?>
<SOAP-ENV:Envelope
   xmlns:SOAP-ENV = "http://www.w3.org/2001/12/soap-envelope"
   SOAP-ENV:encodingStyle = "http://www.w3.org/2001/12/soap-encoding">

   <SOAP-ENV:Body xmlns:m = "http://www.xyz.org/quotations">
      <m:GetQuotation>
         <m:QuotationsName>MiscroSoft</m:QuotationsName>
      </m:GetQuotation>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Enter fullscreen mode Exit fullscreen mode

Pros

  • SOAP is completely programming language and processing platform agnostic because of the standardized format.
  • SOAP APIs come with built-in native error handling, helping developers quickly identify and resolve problems.
  • SOAP APIs are the best suited for transferring sensitive data to and fro such as financial data as its standardization allows a specific contract to be imposed in form of code throughout all of the APIs.
  • Stateful operations are supported by SOAP and may be implemented using the WS-* (Web Services) Specifications, which are built on top of the basic XML and SOAP standards.

Cons

  • Because SOAP can only send messages as XML files, your SOAP API will be less performant, as XML is a more verbose format than JSON.
  • SOAP API requests to your server consume more bandwidth and take longer to process the request and return the result to the client.
  • SOAP client-server communication is based on WSDL (Web Service Description Language) contracts, implying a close connection. As a result, it is not suitable for loosely connected applications since you cannot avoid a contract between the client and the server.
  • SOAP also has a steeper learning curve, is more difficult to develop, and cannot be tested in a web browser (as opposed to REST). SOAP requires you to construct contracts in WSDL, establish client stubs, adhere to tight requirements, and more. As a result, as a programmer, you will have less flexibility in choice.

API Tester supports sending requests to SOAP APIs and allows you to test your APIs without any effort in a quick and easy way.

GraphQL APIs

When Facebook created GraphQL, they required a robust data-fetching API that could perform all of Facebook's tasks while being straightforward and easy to learn and use by their product developers. GraphQL was created in order to rebuild Facebook's native mobile apps.

GraphQL is a query language. It returns a query in the form of a string, which is then submitted to a server. The server processes the query and delivers the response to the client in JSON format.

GraphQL is a strongly typed language in which each level of a GraphQL query corresponds to a different type, and each type represents a different set of accessible fields. As a result, it is similar to SQL in that it offers informative error warnings prior to performing a query, hence the name.

GraphQL has a hierarchical structure in which relationships between objects are defined graphically. Every object type represents a component in this context, and every related field from one object type to another represents a component wrapping another component.

A simple GraphQL request looks like this:

{
  me {
    name
    friends {
        name
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

When migrating from a monolithic backend application to a microservice design, the GraphQL API may assist us in managing communication between numerous microservices by integrating them into a single GraphQL schema.

Pros

  • GraphQL is significantly faster than other communication APIs because it allows you to narrow down your request query by selecting only the data you wish to query. Thus, it resolves all over-fetching and under-fetching problems.

  • Using GraphQL's API, we can integrate numerous platforms. It brings them together while masking their complexities. The GraphQL server is also used to retrieve data from existing systems and package it in GraphQL response format. This is especially useful for legacy infrastructures or third-party APIs that are massive in size and difficult to manage.

  • When we send GraphQL queries to the server, the server responds in a simple, secure, and predictable format. As a result, it makes it easier for you to construct a customized query based on your needs. This makes GraphQL extremely simple to learn and use.

  • At a higher component level, we can share the GraphQL fields used in many queries for reuse. This feature is known as fragments, and it allows you to obtain diverse data while maintaining the same schema field.

  • Because the result set or returned data in GraphQL is highly particular to the client's query, it is quite straightforward and easy for the server to generalize it. When we add new product features or fields to the server, it has no effect on old clients. You can continue to utilize the older server without concern because server fields can be deprecated but still operate. This compatible procedure does not necessitate the use of an ever-increasing version number. As you can see, Facebook uses the same version of GraphQL API in all of its applications.

Cons

  • One downside is that queries always return an HTTP status code of 200, regardless of whether they were successful or not. If your query fails, your return JSON will include a top-level errors key containing error messages and a stack trace. This can make error handling considerably more difficult and add to the complexity of things like monitoring.
  • It is more complicated to implement a simplified cache with GraphQL than to implement it in REST.
  • Rate-limiting is another issue with GraphQL. In REST API, you can easily write "we accept just this many requests in one day," but in GraphQL, this sort of statement is harder to convey.
  • GraphQL is difficult to pick up without lots of training and experience.

GitHub’s GraphQL API is the most commonly used free developer API. Create and run a GraphQL request in API Tester within minutes and get started to explore more!

gRPC

gRPC Remote Procedure Call (gRPC) is a cross-platform, open-source, contract-based communication protocol that streamlines and controls interservice communication by providing a set of functions to external clients.

The 'g' at the beginning indicates that this is the most advanced version created by Google in 2015. On one side, a user will pick a remote process to run, serialize the required parameters, and then attach any additional information to the message. This is then transferred to the server, which communicates with the other application, decoding the message and performing the action. The original user is then given a result.

Pros

  • It is simple and straightforward, GET is used to fetch information and POST for everything else.
  • Functions are simple to add, and for lightweight payloads, overall performance is excellent. Thus, it is endlessly customizable due to the flexibility to define any type of function.

Cons

  • The fact that gRPC is strongly connected to the underlying system limits its reusability in many circumstances is where it falls short. Furthermore, no abstraction layer exists between the API and the real system functions, which raises security problems.

How to Choose the Right API for Your Use?

As you might be able to guess from the above discussion, there is no “best” API type, each of the API types have its distinct characteristics that make them well suited for specific applications. However, the question still remains - how to find the one that works the best for you?

Here are some questions that can help you determine:

  • Which programming language would you like to use?
  • Which environment will you be developing in?
  • What is the most important functionality for this API?
  • What skills do you have on staff? What skills can you acquire?
  • What resources have you set aside for this project?

Remember that you can always run a simple proof-of-concept with one or two types to test how they work. You can also use API Tester, an easy-to-use mobile app that helps you to test any API on your phone.

Conclusion

We hope this blog post was helpful in distinguishing between the most popular types of APIs. Each has a purpose, and when you make a deliberate and considered selection up front, you're well on your way to designing an API that is not just effective but also resource-conscious.

Top comments (23)

Collapse
 
miguelsmuller profile image
Miguel Müller

I'm writing an academic paper on gRPC. The technology offers numerous other benefits as it is linked to other cutting-edge technologies. Soon I will publish this paper.

Collapse
 
ashik155 profile image
Ashik Patel

That is great to hear. Good luck mate.

Collapse
 
vishnumeera profile image
VishnuSankar

could you share to read once you done, like if thats possible

Collapse
 
ankit9761 profile image
Ankit Kanyal

great article had a good read reading it

Collapse
 
lizhang19817 profile image
Li Zhang

Cool!

Collapse
 
richardtorres314 profile image
Richard Torres

Fantastic read! Very well stated. Thanks for this gem!

Collapse
 
pragativerma18 profile image
Pragati Verma

Thank you so much Richard. I am glad that you liked it! 😁

Collapse
 
mcwolfmm profile image
mcwolfmm

Another article comparing protocols with architecture, apples with pears...
it is not clear if you are distinguishing between REST and RESTful (REST over HTTP).

And one small clarification. although rest is a stateless architecture, in combination with http (also stateless by definition) http sessions can be used in restful.

Collapse
 
liyasthomas profile image
Liyas Thomas

This is very informative. Learned a lot about RESTful APIs.

If anyone like to spin up any of such APIs, RESTful, GraphQL, Realtime APIs online - checkout Hoppscotch.io - helps to make requests directly from the browser.

GitHub logo hoppscotch / hoppscotch

👽 Open source API development ecosystem - https://hoppscotch.io

Collapse
 
dominikbraun profile image
DB

SOAP 💀

Collapse
 
radandevist profile image
Andrianarisoa Daniel

I remember, a few years ago searching about SOAP and how to implement it, but barely found any resources. I just gave up and turned into other formats. I don't think it's a thing now in 2022.

Collapse
 
nicolus profile image
Nicolas Bailly • Edited on

It's very much still a thing.

If you book a flight or a hotel there's a good chance it will be transmitted using SOAP as it's still the primary API used by Sabre.

If you use your company's Active Directory account to connect to third party services, there's also a good chance it uses SAML which is built on top of SOAP.

Apparently it's also used a lot in the banking field.

So yeah, noone in their right mind would use SOAP in a brand new consumer web app, but it's very common in enterprise products where security and consistency are important, so it's very likely that you'll encounter it at some point or another.

Collapse
 
llorx profile image
Jorge Fuentes • Edited on

Have not integrated Active Directory that much, but has been always with LDAP. I guess they are reducing SOAP lately.

Another one that uses SOAP is CAISO (California ISO), to manage power plants. A pain to implement actually.

Collapse
 
kvetoslavnovak profile image
kvetoslavnovak • Edited on

Recently in my last project I needed to use SPARQL besides REST and webservices/ SOAP.
SPARQL seems very flexible. A learning curve was pretty high for me though.

Collapse
 
binho3399 profile image
binho3399

Sounds great

Collapse
 
amyswen451 profile image
Amanda Swensen

Every article where SOAP is mentioned has debate in the comments whether it is good or not.

Collapse
 
yukikimoto profile image
Yuki Kimoto - SPVM - Perl Club

Thanks.

Collapse
 
phophogr profile image
Phoebe Green

Great post! One quick question. Is gRPC (HTTP/2) faster than REST with HTTP/2?

Collapse
 
mikedevkelly profile image
mikedevkelly

Do you think that SOAP has a future? From the list of pros and cons in the post, it doesn’t look like pros outweigh the cons, but idk 🤷‍♂️

Collapse
 
alessioferrine profile image
alessioferrine

I think this is possible if WSDL or a similar protocol, which allow generating client proxies, starts to be used for RESTful services

Collapse
 
lovepreetsingh profile image
Lovepreet Singh

Well, I am not clear with the implementation details of an API using REST, SOAP and gRPC

We're hiring!

We're Hiring

We're looking for a Senior Full Stack Engineer to join the DEV team.

Head here to learn more.