In today’s post I’m going to talk a little about what an API is and why it’s a concept that allows us to make several integrations between software in such a way that it allows us to build several interconnected services.
Requirements
As today’s post is more theoretical we don’t need any software or operating system at all.
Steps
- What is an API?
- Case study
- Conclusion
What is an API?
An API is an acronym for Application Programming Interface that basically defines how the communication / integration with the specific software should be done, defining protocols, definitions and restrictions so that the exchange of information is done correctly.
Case study
Let’s imagine that we have an information system that allows us to record some data, the function of recording this data is already a functionality of our system that we can define in an API, having said that, we can define our API based on protocols and definitions that allow us to record this data, modify, delete, update, among others, depending on the functionalities implemented in our software.
As an example, let’s imagine a software and model an API to define the protocols, parameters and responses of each operation that we will make available to anyone who wants to integrate with our software.
The example I’m going to use today is an API that calculates a person’s BMI according to the parameters that the person passes to this service.
As an application protocol we will use HTTP, as a standard definition we will use REST and as a data exchange standard we will use JSON, I know that there are 3 concepts so I will leave a brief description of each one and I’ll leave the description links that best fit the concept that I understand it to be.
HTTP:
“Hypertext Transfer Protocol (HTTP) is an application-layer protocol for transmitting hypermedia documents, such as HTML. It was designed for communication between web browsers and web servers, but it can also be used for other purposes. HTTP follows a classical client-server model, with a client opening a connection to make a request, then waiting until it receives a response. HTTP is a stateless protocol, meaning that the server does not keep any data (state) between two requests.”
more info at: https://developer.mozilla.org/en-US/docs/Web/HTTP
REST:
“REST, or REpresentational State Transfer, is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other.”
more info at: https://www.codecademy.com/article/what-is-rest
JSON:
“JSON (JavaScript Object Notation) is a text-based, human-readable data interchange format used to exchange data between web clients and web servers. The format defines a set of structuring rules for the representation of structured data.”
more info at: https://www.theserverside.com/definition/JSON-Javascript-Object-Notation
Now we can define our API to calculate the BMI of any user who wants to connect to our service.
POST rosem.dev/api/services/bmi
This will be our resource made available within our structure of protocols and definitions.
We will wait for the user to send us a “body” in the following layout:
1
2
3
4
5
6
{
"mass": "floatValue",
"height": "floatValue",
"massUnit": "kg | pounds",
"heightUnit": "meter | inches"
}
As this example is more conceptual and not an implementation one, I will not go into what this implementation would be like at this point, but based on this request from a user for our service, our response would be something close to that:
1
2
3
4
5
6
7
{
"bmi": "floatValue",
"result": "Underweight: BMI is less than 18.5 |
Normal weight: BMI between 18.5 and 24.9 |
Overweight: BMI between 25 and 29.9 |
Obese: BMI between 30 or more"
}
In addition, following the logic of using HTTP, there would be a return code in case of success, it would be a 200.
In case of a wrong parameter or a missing key, we would send a customer error code, for example a 400.
Now we can use an example with values to demonstrate what a request would look like in this hypothetical service using curl:
1
curl -X POST -H "Content-Type: application/json" -d '{"mass": 90.0, "height": 1.85, "massUnit": "kg", "heightUnit": "meter"}' https://rosem.dev/api/services/bmi
The result would be this:
1
2
3
4
{
"bmi": 26.3,
"result": "Overweight: BMI between 25 and 29.9"
}
If you are interested in understanding a little more about HTTP API definition standards, you can consult the OpenAPI definitions and standards at this address: https://www.openapis.org/what-is-openapi
If you are interested in using an API definition tool you can consult: https://swagger.io
Conclusion
In this post I was able to present a brief idea of what an API is, in this case based on the HTTP protocol and what information would be necessary to use this service and how the return that the user would receive when using it would be, I hope I have passed on the minimum of knowledge necessary for you who are reading to have learned something new.
I hope you like it, if you want and can you can share this text, I will be posting new content daily, favorite this blog to have access to new knowledge. Thanks to everyone who read this post.