Pragmatic decisions for your RESTful API: Introduction
This article is the first one of a series of posts concerning RESTful API design, which will describe 20 pragmatic decisions for your RESTful API design.
Introduction
These articles are the result of several years of experience building RESTful APIs, first for the Humanitarianresponse project, and then for the Humanitarian ID project, which are now widely used within the Humanitarian Community.
Designing a successful API means making choices, some of them easy, others much harder. I’ve tried to summarize these choices in these blog posts, going from the easiest ones to make to the hardest ones.
What is REST ?
Before diving into decisions, I think it’s important to understand what REST is. REST means Representational State Transfer. It was made popular by Roy Fielding’s thesis “ Architectural Styles and the Design of Network-based Software Architecture “.
In his thesis, Roy Fielding defines various constraints for a REST architecture. I’ve summarized here briefly the most important ones, as the objective of this article is not to dig deeply in the theory:
- Client-server: separation of the user interface concerns (the client) from the data storage concerns (the server)
- Stateless: each request from client to server must contain all of the information necessary to understand the request
- Cache: the data within a response to a request must be implicitly or explicitly labeled as cacheable or non-cacheable
- Uniform Interface: implementations are decoupled from the services they provide (in other words, you should be able to transition from a nodejs implementation for example to a PHP implementation for your server without your clients noticing any difference in the interface they are provided with)
- Layered system: a client can not “see” beyond the immediate layer with which they are interacting. In other words, a client of a RESTful API does not know if it is interacting with the main server (ie the server storing the data) or some intermediary server used for, for example, load-balancing
Idempotency or idempotence
Idempotency or idempotence is a word used in the REST API world. You can perfectly build a RESTful API without understanding what idempotence is, but since the concept is not that hard to grasp, I thought it was useful to include it here.
An idempotent operation means that if you make the same request repeatedly, you will end up with the same result. For example, a PUT request is considered as idempotent, because if you make the same PUT request multiple times, the resource that you are updating will not change, and the end result (the returned resource) will always be the same.
The next article will talk about how to define and represent your resources in your RESTful API.
This series of articles about Restful API design is also available as an eBook on Amazon, if you need it in a handy format.
Originally published at https://www.gvj-web.com on March 14, 2018.
