Pragmatic decisions for your RESTful API: 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.

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 “.

  • 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.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Guillaume Viguier-Just

Guillaume Viguier-Just

Développeur web et passionné de finances personnelles