I'm a big advocate of the simple explanation. Even more so since I started a Master's degree which advertised itself as a "conversion" to Software Engineering - I am at about the right level, but use what I learned in my (comprehensive, four month) bootcamp every damn day. Some of the others who joined with me are genuine code virgins and it just feels like no-one is making any effort to explain the basics to them. In the spirit of helping - here's my explanation of REST APIs.
Firstly- APIs. "Application Programming Interfaces". Kind of a complicated concept but one that's often demonstrated with ye olde restaurant metaphor - the front end (pretty website) is the customer eating the food, the back end (database and "brain") is the kitchen, and the waiter is the API.
I take issue with this. IMO, and I might be wrong (I sometimes am, apparently):
You come into the restaurant and make an order. //You go to a website and enter a query
The waiter writes down the order. //The data is captured inside a specific format (ie. Json)
The order is taken to the kitchen THROUGH THE KITCHEN DOOR. //The json data is recieved by the back end through the API
In my mind, the API is more like a door than a waiter. Your data is packaged up and sent to a specific location, where it is recieved and routed to the correct place.
APIs then are just code constructs, live, and on the lookout for data. They are on the lookout for data being sent to them. They can have several routes or addresses to which to send the data, and each route has a different set of things to do to that data.
Perhaps your route is "updateOrder" - in which case when the API gets the data addressed that "endpoint" (yes, another new word which sounds scary, but as you can see, it ain't) it will probably have some logic in there to update an order somewhere, based on some info in that data.
Perhaps your route is "allCatPics" and that endpoint triggers the return to you of some more data, including the URLs of many, many cat pictures. This is more common than you might think.
So, what is a REST API? Is it sleepy? Having a massage? REST stands for Representational State Transfer. God knows. You can ignore that. What it means is that your API and its named endpoints follow a set naming convention.
Its beauty is its simplicity - it is easy to follow, easy to guess, and uniform.
Its downside is also its simplicity - we'll touch on that in a moment.
Stepping back - that waiter has a few options when he goes through the kitchen door. He can wave the order and shout "NEW ORDER, CHEF!", or he can shout "TABLE 5 HATE IT AND SENT IT BACK", or he can shout "READY FOR DESSERT ON TABLE 3".
Likewise, our communication via API can take a few approaches. Chances are you've heard of "POSTing" data. You can also "GET" data (essentially the same, except as the name suggests, you are only making a request to receive data back; a la Cat Pic). There are other options like "PUT" and "DELETE". They are just POST in pretty, semantic, dresses. These are called "HTTP verbs".
This is how REST gets to be so simple. Aside from the endpoint names, you need to use the appropriate HTTP verb.
POST => create a new thing
DELETE => delete a thing
PUT => update a thing
GET => get something
So, that's the first part of the rule. The second part is the naming of the endpoints:
POST www.myUrl.com/thing
ie. a post request to /order sends a new bit of data with it. A new order. This needs to be singular. /cat, /person etc.
DELETE www.myUrl.com/thing/id
Singular word here /thing, and then you get to specify what it is you want to delete- usually done with an id, hence the /id.
beware - some APIs will delete all the data if you forget to give them a set ID here.
Same pattern here, but remember above - "put" requests are used to update an existing piece of data. So you can attach some data to this like you did with the POST. Nb. As we discussed, this is actually still a POST request, just in fancy dress. There is nothing technically stopping a PUT request providing the initial piece of data; but in REST rules it is only for updating the data.
Like DELETE, if you forget the ID here, some APIs will update everything to say whatever it is you're sending over here... :D
a singular again; ie the same route word as the ones above. You don't send over any new data, just a request for data. The get route here returns ALL the /things - even though it's singular. I don't make the rules.
here you get an EXTRA thing you can use to just retrieve a certain "thing". The get route within the API code will have some logic in it to check whether you've included an ID, and if you have to just return you that one. Otherwise you get them all.
And a little extra - you can filter using query parameters too. (The query being the bit after the "?").
ie.
GET www.myUrl.com/thing?minAge=18
here is an example of getting all the things that are over 18. You can again implement some logic in the back end to get that query out of the URL, and use it to filter things out of the database to return them. You can use this on PUT, and DELETE too. you wouldn't want to use it on POST in a rest API because you're solely adding new stuff via that command; you can't filter what doesn't exist yet.
So collated with the 4 verbs, you have three possible url structures:
/thing
/thing/{id} (nb it's only in curlies so you know it doesn't have to be an id)
/thing?thing=yes
And that's why REST is so simple. Four verbs, three url endings. The rest of the work is just putting the right combi together for what you want to achieve.
HOWEVER. This can be super restrictive. What if you wanted to get some data for the Things and also the Thangs? You have to do two requests out, one to /thing and one to /thang, and then join that data together at the front end.
Or if you just want to get the Name of all the Things, but the Things are stored with their Fave Color, Haircut Type and Mum's Name too? You have to do a GET request to /thing in order to get the data about all of the things, and then your only option is to filter through that data to just pick out the Thing Name, and ignore the rest. Straightforward, but a waste of resources getting all the info when you only wanted a little bit of it.
Maybe your app just needs to break the REST rules in a couple of places. I wouldn't blame you. In fact, I would say "do not worry, I still have a fancy name you can call your API". It is no longer strictly a REST API, but it is "RESTful". I mean, I would have called it RESTish, but again, I don't make the rules.
I hope this helps understand what people mean when they talk about REST APIs - any if anything is unclear or incorrect, let me know! Every day is a learning day :D
Top comments (0)