Learn about

SOAP, REST & GraphQL

In under 5minutes | Day 1 of #100 Days of Code

This story is not to advocate about any of the above protocols, I believe the best protocol is the one that makes the most sense for you/organization, the types of clients that you need to support, and what you need in terms of flexibility.

SOAP — Simple Object Access Protocol

(But not so simple)

What?

Exchanging data between applications built using various programming languages was the need of the hour back in the 90s, introducing XML — Extensible markup language to serve as an intermediate language between different systems.

Some guidelines were required to be standardized and followed by these “heterogeneous” system so that they have a common format of XML which will be sent across these systems, introducing SOAP — Simple Object Access Protocol, a protocol designed to work with XML and HTTP(default networking protocol for web).

Here you create a WSDL which is like a contract that defines the structure of XML as data format which has to be followed during message transmission.

Pros

• Friendly with Protocols— SOAP can work with a variety of transport protocols and not just HTTP.
• High Security — When security is your priority, SOAP gives you more options in configuration including Data Privacy, Integrity, Identity verification through intermediate layers similar to SSL.
• Recommended by W3C — A body for all web standards
• Built-in Messaging System — To help you deal with failed communications.
• Less Complex at times — For web services that support complex operations, requiring content and context to be maintained, designing a SOAP service requires less coding in the application layer for transactions, security, trust, and other elements.
• Recommended for Enterprise apps, high-security apps, distributed environment, financial services, payment gateways, telecommunication services.

Cons

• Heavy — When compared to other options available today (REST and GraphQL)
• Supports only XML for message format.
• Poor performance
• Doesn't supports caching.
• Not suitable for multimedia files like photos, videos.

REST — Representational State Transfer

(Doesn’t let the devs rest)

What?

In the 2000s as JavaScript became popular, JSON (a message format supported by JavaScript) became popular as well. W3C also released a new architecture supported for web services called REST. The web services that follow this architecture design are called Restful Web Services.

There are 6 guiding principles that have to be followed while developing a web API for it to be called as a REST API.

1. Client-Server — Separate the UI concerns with the storage concerns we improve the scalability.
2. Stateless — Session state is therefore kept entirely on the client. No context is to be maintained on the server.
3. Cacheable — If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
4. Unifrom Interface — REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
5. Layered System — Each component cannot “see” beyond the immediate layer with which they are interacting.
6. Code on demand — REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts.

Pros

• Stateless, hence no server side sessions.
• Supports caching.
• Performant — Faster and uses less bandwidth.
• Scalable, Flexible, Browser-friendly.
• Supports a large variety of data formats whereas SOAP supports only XML.

Cons

• Supports only HTTP Transfer protocol.
• Less secure and not suitable for Distributed environments where a context is required to be maintained.
• Looks simple but isn't! If you want to build a truly REST web service.
• The so much great flexibility comes at big risks as well, REST falls foul to human error and misunderstanding like everything else.
• There is no contract hence the API developer can change something without facing any warning and hence developers will have to make the changes in the client-side.

GraphQL — Query Language for APIs

(Try Hard Replacement for REST)

Over the past decade, REST has become the standard for designing Web Services and APIs but it had its own flaws. As the Internet age is progressing towards mobile topped up with limited computing and network bandwidth a need for a more performant solution was inevitable. Facebook has been working on the same idea and has been using it for a while and released it out to the world in 2015.

Traditional REST endpoints return fixed data structures, usually with extra info clients don’t need and require multiple endpoints (and HTTP calls) to get back all the necessary information. GraphQL does not!

GraphQL works based on strongly typed schemas. Similar to WSDL contract we had in SOAP, everything that you want GraphQL to return to you, must be explicitly defined in the schema. The Schema Definition Language (SDL) is the syntax for writing schemas, and queries and mutations are composed to get back the required information from the server.

Putting it simply, GraphQL return only the data you request for instead of the whole JSON XML Data Structure. This saves bandwidth and makes GraphQL even more performant over REST. Hence, you can say GraphQL was made by picking the best of both SOAP and REST and that is the reason it is very popular and major players have already migrated to GraphQL.

The Goods

• Rapid Prototyping — GraphQL acts as the middleman between the UI and the data storage taking care of how to get the requested data from the storage to the requesting UI. Hence, you as a developer won’t have to write CRUD operations for the same.
• No CRUD Operations, We have Subscriptions! — The client receives real-time messages from the server if the data is updated. If you have used Firebase Realtime Database you will know how pleasing that is.
• Great fit for complex systems & microservices — You can have multiple systems in the server and GraphQL will unify them and abstracts the complexity away from you.
• Single API Call — You can get data from multiple data endpoints/API in a simple GraphQL API call as GraphQL takes care of getting the data from multiple data points for you.
• Better Network performance — As it only sends the requested data hence lower bandwidth consumption.
• Strong typing — A schema is maintained on the server-side which serves as the contract and maintains standards. GraphQL also takes care of Data Validation out of the box for you.
• Developer friendly — especially the devs who are consuming the API as they get what they ask for and the backend devs take care of maintaining the Schema definition while GraphQL takes care of mapping the data efficiently.

REST can be given the above pros if you additionally implement JSON API Libraries and JSON Schema but that is some additional complex work you as a developer have to do which GraphQL gives you out of the box.

The Bad

• More complex than REST in implementation hence takes a bit of learning time as compared to REST. Implementing the same query will take longer to implement in GraphQL as compared to REST.
• Not suitable for complex queries and resource-driven applications — It might not be the best idea to give control over to GraphQL, hence a REST API with your custom logic might be a better option.
• No support for Files — GraphQL doesn’t understand files, hence a REST with POST/PUT request will serve you.
• Maintaincene — GraphQL servers can become bloated if not maintained well.

That’s all for Day 1, hope you learned something valuable out of these story.

Some great resources to learn more about them:

1. SOAP — Guru99
2. REST — Moesif
3. GraphQL — Medium