Hi everyone
Today I thought I would do a quick post to cover RESTful APIs, and what they are. The reason for this article is that I have, on numerous occasions, encountered developers (and indeed whole teams) who have misunderstood this concept at its very core. This causes a number of problems, firstly if you don’t understand RESTful APIs fundamentally, you’re likely to encounter integration issues quite early on. Secondly, unfortunately, if you’re a candidate interviewing for a role and haven’t understood what a RESTful API is properly, you’ll come unstuck in interview.
What RESTful is not (necessarily)
- A buzzword for a JSON API
- An API with obscure functionality
What a RESTful API is, and what it has
- REST is REpresentational State Transfer, RESTful is an adjective, so a RESTful API is an API which subscribes to the REST principles
- The purpose of REST is to ensure that APIs are easy to understand at a universal level
- RESTful APIs will have end points which represent entities
- Those endpoints will respect HTTP methods (also referred to as verbs) to represent the actions you wish to take
Okay, so explain to me the HTTP methods/verbs
- GET requests represent reading this entity/collection from the data source
- POST requests represent creating an entity/collection in the data source
- PUT requests update (destructively, replacing) the entity in the data source
- PATCH requests update (partially) the entity in the data source
- DELETE requests remove the entity from the data source
How does that work in practice?
Let’s use the example of a payment provider, you may have entities such as
- api/customer
- api/payment
- api/payment/paymentId/refund
You will always need a specification, but theoretically you know that if you send a POST to endpoint/customer you will create one, if you send a PATCH you’ll partially update that customer. If you send a POST to api/payment you will create a payment, for which you will receive a reference (ID), and if you were to send a POST request to api/payment/id-you-received/refund then you would create a refund against the payment which you specified in the payment ID.
So what’s the point?
The main idea behind RESTful APIs, the same as with other standards such as PSR-X, is to unify the way in which we build APIs, so if I were to say, for example, to an organisation with whom I am going to be integrating “we have a RESTful API you can integrate with” they know, with some level of certainty, how much work there is involved in working with it – they also do not have to have an in depth understanding of my local design, architecture, etc, because the RESTful design abstracts any need for that knowledge.
In summary
RESTful APIs are great, other APIs which are not RESTful can also be great. I just wanted to help inject some clarity on the topic, although, of course, there is plenty of information on the internet around this particular methodology. If one person reads this article and gains an actual understanding of what RESTful is, then it has served its purpose.
Edit: HATEOAS further reading
Valid point raised by DarkTechnocrat on Reddit, for further reading beyond a very basic understanding on REST, you probably should read up on HATEOAS – at a quick glance this article on spring.io looks like a good place to start 🙂
Thanks for this clear and concise overview of REST.
One of the big mistakes that people make when designing RESTful APIs that I’ve seen is that they design RPC (remote procedure call) endpoints. For example, you have an URL that indicates the server has to execute a specific action, instead of creating / updating / deleting an entity.
The example in your article above, for refunding a payment, is not wrong, but you should be careful to not understand it the wrong way. POSTing to the api/payment/{paymentId}/refund URI does not mean: server, execute a refund for this payment (which would be an RPC-style call); rather it means: server: create a refund entity for this payment. (And ofcourse, the server will then at some point process that refund entity and refund the payment).
You could emphasize this in your article – I think it’s one of the fundamental things people need to understand about RESTful APIs.
An entirely valid point, that example has raised some comments on Reddit as well, I have recently been working with a payment provider so it was a fresh one to mind, but you are 100% right; thanks for sharing
A quick comment for those coming from Reddit – I usually aim to respond to all comments/threads when I share something, but with approaching 100 comments, I don’t think I’m going to keep up somehow – but will try haha
Pingback:Newsy programistyczne 2018-06-03 – DevNation
An (IMO) important point missing is that REST, the architecture, is stateless. Thus, RESTful APIs must reflect this: Clients always need to send all information to the server so that it knows everything it needs to know solely with the data in the request. There is no session on the server that ‘survives’ a request, but there is likely to be a token of some sort if authentication and authorization is involved.
In my experience most people and teams fail to implement a service as REST, thus it gets hacky when a RESTful API should be attached (a strong indicator that something’s off). (One could also decide against using REST, but that’s a different discussion.) To my understanding, a common problem is that teams don’t know what the software’s ‘collections’ are – the things you GET/POST/PUT/PATCH/DELETE via the API. Once that is clear, the RESTful API should be easy to spot.
REST is a simple solution – to get it right can often be challenging.
I’m so sorry for taking so long to approve this, I didn’t spot it amongst a number of pings and other things
You are absolutely right, and in integrating with lots of “RESTful” APIs, as you say, is that actually the team cannot agree on what the resources are, or more to the point they implement this using internal tribal knowledge, without considering the lack of documentation of this tribal terminology, language, and understanding that the integrating developers will need to know
You are right about the REST architecture and it’s stateless nature, I omitted this really because (IMO) this is the case with all API development, as opposed to those which specifically subscribe to the REST principles