A recent state of API 2020 report found, from 3,536 responses, that 82% of respondents use the OpenAPI as a common standard for defining APIs (page 49). It is a clear winner, making it important to know how to implement your APIs using it. Further to this, how does CRUD (Create, Read, Update, and Delete) relate to it?
To answer this meaningfully, this article is going to start with some basics so we can answer the main question. So, first up, lets conquer these ones:
- What is CRUD?
- What is an API?
- How does CRUD relate to an API?
- What is the OpenAPI?
- How do you implement an OpenAPI?
- Summary: Lets put it all together
What is CRUD?
CRUD is a concept you will find across many parts of software development. It represents the four basic operations you can perform on any data.
- You can create something.
- You can read it. Or some people like to say retrieve it.
- You can update it.
- You can delete or remove it.
That’s it! All operations can be categorised as one of these four (or a combination of them). The reason it all boils down to these four is that software is constrained by the underlying hardware and, without delving into the details of microcontrollers, the result is that the concept of CRUD can be found in lots of different parts of software engineering.
What is an API?
An API (Application Programming Interface) is another term you will find loosely thrown around. Like CRUD, it is a concept that can be found in lots of different parts of software engineering. The most important word in the acronym is interface, and simply means something you can call and get a result back.
In the following sketch, you can see the simple flow of input, process, and output. Some input comes in. The process then does something. And then the output goes back. This is also a constraint of the underlying hardware.
So, an API (or interface) simply defines what input is allowed to come in and what output can be expected to go back. The better APIs will also have documentation describing what can be expected of the process and what will happen if something goes wrong, like illegal input or an internal error.
Taking this one step further, the above sketch can be applied to the way the web works. Hopefully you have heard of HTTP? It is the protocol used to communicate across the web and you would see it prepending website names like https://lmgtfy.com/. In the following sketch, you can see that the input, process, and output has been replaced by HTTP request, server, HTTP response.
Like our first sketch where an API is defined in terms of input, process, output; the HTTP protocol can be used as an API across the web.
How does CRUD relate to an API?
Under the hood, the HTTP protocol specifies a number of request types. Remember, a HTTP request is the input to a process, and here is the super important thing to remember, the HTTP request types are CRUD! Checkout the following table:
| CRUD | HTTP |
|---|---|
| Create | POST |
| Read | GET |
| Update | PUT |
| Delete | DELETE |
If you want to create something new, you use a POST request. For a read, it is GET. And so on… That is pretty cool to know and you will find this everywhere in APIs like the OpenAPI.
There are a few more HTTP request types than these four, but they are the main ones to know about. If you want to get more technical and dive deeper, take a look at this great documentation from our friends at Mozilla on HTTP request methods.
What is the OpenAPI?
Let’s do a quick recap before we talk OpenAPI to cement our knowledge. So far, we know that CRUD is the four basic operations you can perform on any data. We know that computers are constrained by their input, process, and output. This leads us to an API (or interface) that helps define how we can use them. We also know that HTTP is a protocol that has four HTTP request types (or four inputs) that represent the four basic operations of CRUD. Now, if you can follow along with this paragraph, you are doing great! Let’s talk how the OpenAPI fits into the puzzle.
The OpenAPI originally spun out of Swagger and was an initiative to standardise APIs on the web. Believe it or not, software engineering is a bit like the Wild West and there are many different people doing lots of different things. So, in an effort to make things standard, Swagger was born and due to its popularity, became the OpenAPI standard.
Don’t get frazzled by the word standard here. I have seen students eyes glaze over when you say this word because they think it is something mystical like quantum mechanics. A standard simply specifies the way we all should do something. For example, in some countries you drive on the left-hand side of the road and in other countries on the right-hand side. This is a standard and there will be a set of rules for that country telling you what you can and can’t do.
A software standard is like this. The OpenAPI standard gives you a set of rules for how you can define, implement, and invoke APIs on the web. Checkout the OpenAPI specification and do a search for PUT, GET, POST, or DELETE. You will find them scattered throughout the document.
How do you implement an OpenAPI?
There are a bunch of great tools out there to help you implement an OpenAPI. Of course, Swagger was the original source and there are many tools available on their website. You can also checkout the Postman app, which is handy for manual testing. One of the coolest tools is Swagger Codegen. Using code generators can simplify your build process by generating server stubs and client SDKs from the OpenAPI. This can get you some quick wins!
There are a couple of gotcha’s to look out for though. Firstly, the code generator only gives you skeleton code and not a full-stack implementation. Secondly, if you want to change anything in the API afterwards, the code generator could overwrite your implementation, which is annoying and you just end up having to hand code it again anyway.
At Codebots, ours bots write full-stack applications that can be customised including an OpenAPI. To show how this works, let’s use a running example of a simple movie application. As seen in the following screenshot, we have a entity diagram where there are movies, actors, and categories.
When building, the codebot writes a full-stack application and the OpenAPI including documentation and tests. The codebot uses the entity diagram shown above to write the APIs. As you can see below, there are controllers (APIs) for each of the entities described in the diagram. When working in your local development environment, you can access the OpenAPI docs at [http://localhost:8080/swagger-ui.html (SpringBot) or http://localhost:5000/api/swagger/index.html (C#Bot). The following screenshot shows you the result.
In the next screenshot, the result of clicking on one of the APIs is shown. In this case, the movies-controller was clicked and you can now see all the different HTTP request types; PUT, GET, POST, and DELETE. There it is! CRUD on your data and in this case, the movies in your application.
Having this OpenAPI massively unlocks your application. You are now ready to integrate with other applications and also make your customers happy by allowing them to integrate with you. One final note before the summary, 47% of the organisations surveyed in the state of API 2020 report deal with API Documentation that is now out of sync with the API implementation. The good news is that the documentation written into the entity diagram in Codebots is used in the OpenAPI docs, so the problem of the documentation being out of sync can be mitigated.
Summary: Let’s put it all together
Now that we have looked at and examined a bunch of different terms like CRUD, API, and how they relate to each other and the OpenAPI, let’s return to our original question and see if we can answer it meaningfully.
How can you implement CRUD using an OpenAPI? The answer is that the OpenAPI sits over the top of HTTP and the HTTP protocol specifies the four basic CRUD operations as PUT, GET, POST, and DELETE. These four operations are part of the OpenAPI specification. To implement an API in the OpenAPI standard, you can consider using Swagger to code generate some skeleton code or you could take it further and use a codebot to write a full-stack application.
Hopefully the above answer is satisfactory for you. If you did follow along, awesome! Well done. If not, revisit the sections above and spend some time thinking about some of the constraints we discussed; like how the input, process, and output comes from the underlying hardware, and how all operations on data can fall under one of the CRUD.
CRUD has possibly one of the worst coincidences as an acronym. The dictionary says it is a substance which is considered unpleasant or disgusting, typically because of its dirtiness, but we know that it is way cooler than that, representing the four basic operations you can perform on any data. Instead of it being unpleasant like a load of crud, we like to be more positive and just crud on!
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.
