REST API – Dealing with Problems

Here’s how it looked in recent years:

• in 2014 to Backbone.js,
• in 2015-16 to AngularJS,
• in 2017 to Angular 2/4,
• in 2018 to React.js,
• What will be next? Vue.js?

as well as some Back-End (Java, Python, CF, Node.js etc.) providing REST API endpoints.

This setup moves a lot of data, fetching and processing code from the Back-End “BE” (web server) to the Front-End “FE” (web browser, mobile app). It makes development easier at the Back-End, but hugely increases complexity at the Front-End. Added to this, it introduces a new set of problems with API compatibility.

Advantages of switching to REST API

In theory REST API should only have advantages, which include:

• much better, responsive UI,
• moving HTML generation from BE to FE where it’s easily and quickly updated,
• system decoupling,
• allowing for the independent development of FE and BE (at least in theory).

Problem

Real life vs REST API

But in practice (and practice always beats theory in IT), for most developer teams, it mainly causes huge problems with data incompatibility on REST API endpoints.

Those problems become worse with multiple Back-End steps (e.g. microservices) BE->BE->FE and vice versa in terms of writing data FE<-BE<-BE, leading to wasted hours for all developers, and causing frustration for the client/product owner.

Even worse is when API parts were developed by teams in another office/country – hours turn into days and weeks wasted.

Those differences arise from real life situations e.g.:

• another developer changed the API endpoint (FE or BE but not both),
• FE and BE were not deployed at the same time (and without API versioning),
• a typo in the API call, which is hard to debug,
• bad status code and lack of debug info at an API endpoint.

Solution

Use a design guideline

In general it helps if you follow some REST API design guidelines (e.g. this or that). But it won’t completely solve all the problems above. Usually, we can’t control all parts of API in large systems. So your guideline stays “on paper” and has no meaning in practice. Moreover, there’s no automatic way to check if API follows any chosen guidelines as they’re only articles in human language. Apart from following a guideline, your API endpoints have to agree on both sides.

Use autogenerated documentation and testing

We need something to rely on – documentation that auto-tests itself, and would track the problem instantly and automatically as opposed to manually.

Manually written documentation quickly becomes obsolete, and is thus misleading, and it damages developer workflow. As a result most developers neither read it, nor trust it.

Manual API tests have to be repeated hundreds of times. They are also difficult and time-consuming (e.g. setting and managing data in POSTman). But it is still common practice in most IT projects to do so. Fortunately the automation of both is fairly simple to implement.

Use Tools

Step 1 – Autogenerate documentation

Most developers are familiar with REST API tools for describing and documenting REST API endpoints like:

• Swagger
• RAML

For a comparison, click here.

Both include plenty of useful tools and integrations:

• https://raml.org/projects
• https://swagger.io/open-source-integrations/

Generating Swagger definition format (describing an API Endpoint on the server side in detail) with Swagger UI view from source code is also becoming increasingly common (e.g. Hapi.js with Swagger plugin, or JAX-RS with annotations).

But it still doesn’t guarantee that docs will fully agree with code behavior. In complex systems you don’t have control over all API endpoints, nor can you change them or make them autogenerate docs.

Step 2 – Automatic API testing

If you’re lucky and have all endpoints fully documented and described with Swagger or RAML, you can use tools to automatically create and perform API with very little effort:

• for Swagger (https://swagger.io/commercial-tools/),
• for RAML (https://raml.org/projects), e.g. Abao.

It’ll be a huge benefit in terms of daily development.

But getting back to reality – it can only happen in small projects. Typically you don’t have that comfort, and you have to write automatic API tests yourself.

For that, I highly recommend Frisby.js. API tests are very easy to write and require little code. They run in seconds and can be set up to operate automatically.

Summary

The biggest problem with REST API is agreeing on endpoints. It results in additional work and takes longer, and the issue of incompatibility must always be taken into account. At the very least, you will be forced to identify the part of the system which is causing the problems, then guess who should fix the problem and assign it to them, of course hoping it won’t be reassigned over and over again. It’s a waste of time.

A quick trace of REST API bugs and assigning them to the responsible developer is the key to a successful “modern web” project. The tools mentioned in this article are just examples. Find and use the tools that suit your workflow best.