How would you determine if your client should opt for a REST API?

Clarifying Questions

With questions like these, it’s good practice to take a step back and prepare some clarifying questions before you begin to form a recommendation.

Here are a few considerations to keep in mind:

• Is the amount of network traffic sent between consumers and the client’s server a factor to be considered? (challenge: How would this influence your choice of SOAP or REST API?)
• Does the client have the skills to build complex APIs or will they have to outsource API creation / maintenance?

Because we know (from the question) that the client plans to roll out mobile apps for customers in the future, it’s important to consider which APIs are easily scalable. When you’re ready to begin defining requirements, here are some direct questions you might want to ask your interviewer.

• What security requirements exist? Who will be accessing the API, and for what reasons?
• What’s the timeline for this project?
• What elements of the customer experience are most important?

After some back-and-forth, assume you gather the following requirements from the interviewer:

• Consumers should be able to order products directly through both the client’s website and mobile apps.
• The client wants to enable security and only wants authorized parties to call its APIs, such as CreateOrder, FetchOrder, CancelOrder, etc.
• The client wants the website and app to be ready as quickly as possible. In addition, the client wants vendor API adoption to be as seamless as possible.
• The client wants the application to be easily scalable.
• The client wants to enable caching at times of high traffic load to ensure a great user experience.

Let’s assess our API options considering each requirement above.

Our Approach

Let’s look at the requirements in detail and discuss whether REST APIs are suitable.

Requirement 1: Consumers can order products through the client’s website and mobile apps.

Since consumers should be able to use both the website and the mobile app, one of the major considerations will be the size of messages being exchanged between the customer’s website/app and the client's IT systems. We want this to be as low as possible.

REST APIs primarily utilize JSON, which is significantly less verbose than XMLmessages sent over SOAP – one of the main reasons REST APIs have shot into prominence over the last few years.

Let’s look at a quick example. This is what a typical XML request sent over the SOAP protocol looks like:

As you can see, it needs a SOAP envelope, which contains, a header and a body. This makes the message “heavy”.

This is how the same data looks in JSON format over a REST API:

The difference is clear. Thus, for interaction with websites and mobile devices, it is always recommended to use JSON over REST to minimize the amount of data being sent over the network. In addition, if XML or even HTML is needed to be sent with a REST API, it is possible due to the flexibility of REST APIs and does not need an envelope like SOAP APIs.

Requirement 2: The client wants to enable security and only wants authorized parties to call its APIs, such as CreateOrder, FetchOrder, CancelOrder, etc.

SOAP is primarily a messaging protocol. The main line of defense when using SOAP is Web Standards (WS) Security – a set of rules that provides capabilities to include passwords, security tokens, and XML encryption with each message.

Because SOAP provides these security considerations out of the box, SOAP APIs were often used for internal data transfer within enterprise IT landscapes where the security of the systems is paramount.

In comparison, REST APIs support HTTPS, a traditional web security mechanism. Thus, the message is secured only in transit through HTTPS, and there are no out-of-the-box security features like passwords, etc.

Thus, security is a key feature of REST API design. Luckily, there are many great options. REST API authorization / authentication methods like HTTP basic authentication, JSON web tokens, API keys, and OAuth can be used to prevent sensitive data leakage.

Tip: Read up on authorization / authentication methods here.

Remember that the APIs we are building are public-facing. Using SOAP APIs would add a layer of complexity we do not need, which can lead to poorer performance. An API-led architecture, with REST APIs secured using API Gateways, is a popular solution. This approach provides features such as authorization / authentication, rate-limiting, traffic surge protection, and much more. Thus, even though REST APIs don't provide needed security capabilities out-of-the-box, they are probably the right choice considering all factors.

Requirement 3: The client wants the website and app to be ready as quickly as possible. In addition, the client wants vendor API adoption to go as seamlessly as possible.

REST APIs are the clear winner here since one of the main benefits of REST is that they are easily understandable. REST works over HTTP protocol, making use of HTTP verbs known by almost all developers, like GET, POST, PUT, DELETE, etc.

Even newbies find them very self-explanatory. For example, GET retrieves information such as order details. POST sends and places information, for example, adding an item to a cart, and so on.

Developers with knowledge of REST are much easier to find than developers with in-depth experience with SOAP. In addition, languages/frameworks used for website and app development, for example, javascript, work seamlessly with REST and JSON, which would be critical if the client wants to ensure vendors can interact with their APIs as quickly and seamlessly as possible

Requirement 4: The client wants the application to be easily scalable.

One of the core principles of REST is that it's stateless on the server side, making scalability simpler. “Stateless” simply means that each request is processed independently from the previous ones.

In applications that maintain a server-side state, a session is stored for possibly every logged-in user. The session data, at times of high traffic load, can get very large and occupy huge amounts of resources. Stateless servers, on the other hand, only use resources when actively handling a request. As soon as the response is sent, no data or information related to the state of the request is stored on the server.

Requirement 5: The client wants to enable caching during traffic spikes to ensure a great user experience.

Caching is a common strategy for providing a great user experience in modern web applications. A well-defined cache policy can dramatically reduce the amount of load the client’s servers handle, which leads to a better user experience.

REST makes caching easier. Since the server is stateless and each request can be processed individually, GET requests should usually return the same response regardless of the previous one.

This makes the GET requests easily cacheable and modern browsers display data from the cache itself rather than querying the client’s servers. We can also make our POST requests cacheable using Cache-Control and Expires headers. Some of the common cache headers used are:

• Expires: It specifies the time at which cached data from a GET request, for example, the contents of a user cart, will not be valid anymore, and the client’s IT server would have to be queried again to get the latest state of the cart.
• Cache-control: This can contain multiple properties, such as whether the response is cacheable, and the maximum amount of time the response is valid for.

Tip: Read up on caching strategies here.

Recommendation

With the explosion in mobile device usage over the past decade, REST APIs are now the default way of communication on the internet. They are flexible, scalable, and lightweight and fulfill most of the requirements any modern application can possibly have.

While they have fewer security features out-of-the-box compared to SOAP APIs, this can be easily overcome by using other security mechanisms like OAuth, API keys, etc. with REST APIs. The advantages of REST APIs far outweigh the disadvantages in this case, thus we would suggest the client proceeds with implementing REST APIs.