A recent state of API 2020 report found, from 3,536 responses, that 82% of respondents use REST with OpenAPI and 21% use REST, but without using OpenAPI (page 49). So, REST is the dominant standard with JSON Schemas, WSDL, GraphQL, and gRPC still in the mix. So knowing REST is important and how REST relates to CRUD can help with your understanding.
For a simple example, we are going to use a movie application. The following screenshot shows a simple entity diagram (or database schema if you like) of the application. There are movies, categories, and actors. For this simple application, a common requirement would be to create a REST API that allowed users to manage their data using CRUD operations.
In the following table, the rows show the tight relationship between CRUD, HTTP, and REST. To create something new use a POST request and call the REST endpoint /api/movie. To read something use a GET request and the call the REST endpoint /api/movie/{id}. The id is passed as an argument to the endpoint. To update something use a PUT request and call the REST endpoint /api/movie. To delete something use a DELETE request and call the REST endpoint /api/movie/{id}. Use the id parameter to pass the unique identifier of what you want to delete.
| CRUD | HTTP | REST |
|---|---|---|
| Create | POST | /api/movie |
| Read | GET | /api/movie/{id} |
| Update | PUT | /api/movie |
| Delete | DELETE | /api/movie/{id} |
It is generally accepted that PUT is used for update but you may find some implementations that allow a create as well. It is important to read the API documentation to find out its intended behaviour.
A short history of REST
REST comes out of a doctoral dissertation, which is very inspiring as Codebots comes out of a doctoral dissertation too. Roy Fielding proposed Representational State Transfer (REST) architectural style in chapter 5, and it is worth having a read of the linked proposal. He was inspired to follow an approach with an emphasis on starting with an empty set of constraints and building up from there. In other words, something that solved a problem with the minimum needed.
Roy published his dissertation in 2000, and it took some time before REST started to gain popularity. There was another protocol at that point in history that was the popular choice, it was called SOAP. The problem with SOAP is that it is very heavy and there was a lot to do to get something basic happening, this frustrated software developers. So, when REST appeared on the scene with it simplicity and minimal approach, it took off. There were two big things that developers loved:
- APIs (like the one in the table above) could be created quickly without having to do the heavy work associated with SOAP. In Roy’s dissertation he stated that “REST relies instead on the author choosing a resource identifier that best fits the nature of the concept being identified. Thus, giving permission to do what worked best.
- JSON could be used for the payload instead of XML. If you are unfamiliar with those terms, think lighter instead of heavier, again feeding into that idea of minimal. Developers had begun an aversion to XML which SOAP uses heavily.
Over time, SOAP has addressed the issues around being too heavyweight to become more usable, but the ship already sailed and a lot of people now just use REST. However, to help give a little bit more structure to REST, Swagger was started in 2010 to help standardise and document APIs. In 2015, Swagger was donated to a Linux Foundation project called the OpenAPI Initiative and remains open-source. For our movie application, we would end up with an OpenAPI that looked like the following screenshot.
Summary
Create, Read, Update, and Delete (CRUD) correlates to the HTTP protocol’s POST, GET, PUT, and DELETE, which REST is built on top of. Having an understanding of the relationship between CRUD, REST and HTTP creates a solid foundation about how to use web services and APIs better.
A small note for the summary, is to encourage the readers to go through some of the links in this article for more background information and answers to some of the deeper questions; are there more HTTP request types out there? And what role do these request types serve?
If you are interested in learning more about the OpenAPI, you can read up on how can you implement CRUD using an OpenAPI. Also, a big thanks goes out to Roy for his doctoral dissertation on REST and his work on HTTP. Some might think of Roy as a visionary like Buzz Lightyear, to CRUD and beyond!
Written by Eban Escott
Founder of Codebots
Dr Eban Escott received his Doctorate from UQ (2013) in Model-Driven Engineering and his Masters from QUT (2004) in Artificial Intelligence. He is an advocate of using models as first class artefacts in software engineering and creating not just technologies, but methodologies that enhance the quality of life for software engineers.
