Integrations 101: RESTful API

Is a RESTful API very calm?

The first and more obvious question is, does RESTful mean what it sounds like? Is the API very calm? It doesn’t appear to be that simple. The terms RESTful and RESTless refer to security aspects of the API, which deserve a separate blog.

For now, we can keep the explanation of the name to: a RESTful API meets the set of constraints defined as REST.

What are these constraints?

Would be your next question.

We hear you. These are:

• Uniform Interface
• Client-Server
• Stateless
• Cacheable
• Layered System
• Code on Demand

If you are lost, don’t worry. Overall, the important thing to remember and the implication of the constraints is that by design, REST is geared towards less structured and bulky data, that is typically handled by mobile devices. Therefore, the nature and purpose of the application that the API is designed for, will determine whether REST is the best choice or not. There are several other options out there, such as SOAP and GraphQL that are explained in different articles.

Last bit of geek terminology for this introduction, to round things out: REST stands for Representational State Transfer. Just so aside from knowing it is nothing like a ‘calm’ technology, you know what it stands for. Even though it goes beyond this blog to further analyse those words.

What does a RESTful API do?

In short, a RESTful API allows a system to interact with the application it belongs to, to do the following data operations:

• GET
• POST
• PUT/PATCH
• DELETE

In plain English, this means data is read from, inserted into, updated or deleted from certain defined locations in the application. Once read, the data can also be exported to be used in some other way via the API, by downstream software. It is here that Harmonizer would process data, to deliver to downstream systems (GET), or add, delete or update data in the application itself (POST, PUT, PATCH, DELETE).

How standardised is the standard?

This is the crux of the issue, and something we’ve alluded to in many past blogs. Not very standardised. REST offers a standard structure to encapsulate the operations of GET, POST, PUT, PATCH and DELETE, but it is more a school of thought/philosophy based on principles, rather than a set of hard rules or predefined code. The result is that one RESTful API does not look like the next one at all.

If you are designing and implementing a RESTful API, there are many choices that need to be made, such as:

• What kind of operations do you allow through your API? Remember these choices have security implications too.
• How do you require the client to hand over the data and the parameters?
• What kind of filtering options do you give and what complexity?
• Do you include relational data (for example the orders of a customer)?
• Do you apply paging and how?
• What do you include in the response after update / create?
• How do you transfer files?

This means that you can’t write one piece of (integration) software that can interact with all possible RESTful APIs that exist. In practice, for every RESTful API out there, slightly different code will have to be written in order to interact with it. This inspired our modular design for Harmonizer’s architecture, amongst other things.

What are some low-tech analogies to further explain the REST standard for APIs?

We had to think about this one. Some ideas like apples (you can compare apples to apples, but that does not mean they are the same. E.g. a Granny Smith tastes nothing like a Pink Lady) and dress codes (but what does black tie even mean?!?) crossed our minds.

The winning analogy was - believe it or not - about cars. Because cars are semi-standardised, but allow for a great deal of design and other detailed flexibility in terms of the specifics. There are standards and constraints out there that cars need to meet, or else they won’t be allowed on the road.

At the highest level, we also have agreement regarding what a car looks like. For example, we know that a vehicle that has a gas, hydrogen or electricity powered engine with four wheels and one or more doors, is likely a car. A deviation of this, e.g. a skateboard however, is not a car.

So we have a definition, a standard, some constraints, but that leaves a lot open in terms of the actual design of the car. Such as the shape, the colour, the specifics of the engine, interior and accessories. It would be impossible to write a piece of text that explains all the cars in the world adequately at that level of detail.

And a slightly more technical example?

This can be found in the USB and HDMI standards. These standards also provide some guidance, for example regarding the varieties of plugs that are considered part of the family - note these already branch out in several options. Then there are bandwidth varieties, whether the cable conducts electricity, and other elements that influence speed, data transfer and broader functionality.

Conclusion

A main takeaway is that a RESTful API is very useful as a guide for API design, under the right circumstances. Secondly, the understanding there is a lot of variability between one RESTful API to the next.

And finally, we hope the analogies of dress codes, apples, cars and USB/HDMI cables have shed some light on what the REST standard and its constraints entail. If you have any other great analogies, please share them with us!

Photo by Georgie Cobbs on Unsplash