On our blog you could and will see the acronym API many times. The definition of this word is usually very general. This acronym is used in many contexts. My goal in this article is to list and explain all of them one by one and give you foundation of how to build APIs in a clean way.
We use the acronym API all the time. We say that function can expose some api, module can have api, component has api, service’s api, we write REST api, we can expose and consume API. Under the API in common programming speech can hide many things. For a new to programming person it may be confusing. Let’s decode all the contexts and meanings, piece by piece.
Dry definition:
API is an application programming interface [API], i.e. a set of rules strictly describing how programs or subprograms communicate with each other [9]. ~ Wikipedia
API is just a form of communication
However, the word API often means more than a list of guidelines. Generally speaking, an API can be defined as anything that enables, facilitates, and makes secure and predictable interactivity between applications or even their parts. This is how applications talk to each other but not only them.
Something that is most often associated with API is a form of communication with the back-end in the form of a set of so-called endpoints. The endpoint is the end of the communication channel between applications. Most often represented as the server url pattern (simply the url of the backend application). Examples of such patterns you will see in a moment.
API in a smaller scale
However, one part of the Wikipedia definition talks about subroutine communication. Translating it into practical language – programmers use the abbreviation API in the context of the application, but also its parts. That is, for example, a framework, a library, but also a module, class, method or function.
API is often identified with a set of functions, public methods and properties with which you can use a class or a piece of the system in general. The API can be part of a library or framework that is a reference by which you use this technology in your code. An API is often just an interface through which you can use some part of the code, such as function parameters. When we declare function’s parameters they become functions’s API, because through them this function is able to “communicate” with the outer world. Generally, an API can be seen as anything that allows interaction in between programs and/or parts of it.
API is an abstraction
The API can be an abstraction, a layer separating communication from the details of the system’s operation. It is even very often to extract additional layer of the application responsible only for handling communication and sending messages further to another, more specialized parts of the application (layer of endpoints). If the API is well designed, it can remain the same even with changing details of the system’s operation.
it’s a guarantee that the API will function as intended.
API is a guard
The API also plays a protective role because it determines the method of communication with the system. For example by setting the methods of authentication. In addition we can optimize the way our system performs by dividing it and its data into individual parts.
Moreover, an API is a form of clearly defined contract and the documentation. It represents an agreement between the parties: if party 1 sends a structured remote request, this is how the party’s software responds. Following the rules of an API ensures that we can expect to receive the specific output that the underlying code behind the API is designed to deliver. In other words,
An API is also a set of definitions and protocols for creating and integrating application software. APIs allow an application or service to communicate with other products and services without needing to know how they are implemented. This can simplify application development, saving time and money. When designing new tools and products – or managing existing ones – APIs provide flexibility, simplify design, administration, use, and create opportunities for innovation.
REST API
In 2023 the most commonly used standard for shaping APIs is REST.
REST stands for Representational State Transfer, a term coined by Roy Fielding in 2000. It is an architecture style for designing loosely coupled applications over HTTP that is often used in web service development. REST doesn’t enforce any rule about how it should be implemented at a lower level, it just puts high level design guidelines and leaves a lot of freedom in the implementation.
REST architectural constraints that make the service a true RestfulAPI:
Uniform interface
A resource in the system should only have one logical URI, which should provide a way to retrieve related or additional data, e.g. API/cards should return all cards
Client-Server
This limitation basically means that the client application and the server application must evolve separately without any dependency on each other. The client should only know the resource URIs and that’s it. This is now standard practice in web development, so nothing special is required from the server side.
Stateless
The server does not store any information about the last HTTP request sent by the client. Each request will be treated as new. No session, no story.
Cacheable
In REST, caching should be applied to resources when applicable, then those resources MUST declare themselves cacheable. Caching can be implemented on the server or client side.
Layered System
REST allows you to use a layered system architecture where you deploy APIs on server A and store data on server B and for example authenticate requests on server C. The client is usually unable to tell if it is connected directly to the end server or with an intermediary along the way.
Code on demand
REST rules allow you to extend the functionality of clients by providing them with ready-made code snippets, ready for execution. Most of the time, REST returns static data in the form of e.g. JSON, but the design principles of RESTFful services do not prohibit sending executable code to clients as well.
In most cases, static representations of resources are sent in the form of XML or JSON. But when needed, executable code can be returned to handle parts of the application, e.g. clients can call an API to get code that renders a UI widget. It is allowed.
REST in its most basic form is a rule that dictates the format of our endpoint URLs. Rest is most often used using HTTP due to the correlation of rest rules with htttp methods. However, REST is not strictly related to any protocol. This style is resource oriented. The way in which URLs are formatted, similarly to http methods, reflects the operations that we can perform, for example, using databases, such as creating, updating and deleting resources.
Example of the REST API
Getting data using HTTP GET method:
Path /posts will return to a client list of all posts stored in the database.
By adding id client will receive a specific post (corresponding with sent id)
/posts/:id
If we use HTTP POST method using the same url adddress:
/posts
application creates a new post.
By using PUT on the other hand we can update the post (corresponding with used id).
/posts/:id
Rules for building clean RESTful APIS
- Resource names should be plural nouns. Verbs should not be used. This is especially important from the point of view of readability. This type of convention makes the API self-documenting and we understand it intuitively. Using the plural as the base and id when reaching for a specific resource makes it easy to know and distinguish what data you are reaching for.
- A REST API should accept and return data in a popular format. JSON is most commonly used for this purpose.
- Take care of error handling. That is, for example, use the appropriate error statuses. This improves the code maintenance experience. Thanks to the well-groomed error handling, programmers are able to find and fix them faster.
- Use resource nesting and path parameterization. By using nesting, we are able to better manage resources, return more precise data. This makes our application more flexible. Using parameterized queries makes this process even better.
- Create meaningful documentation. Documenting your code is a very important part of improving your code experience. API documentation is especially important because it gives API users details on how to use it. The more complex the API is, the more important it is.
- Keep your API secure. I don’t think I need to elaborate too much on this. By exposing your API as an easy bite for hackers, you put the data stored in it at risk.
Summary of What is an API
Api is a set of guidelines that establishes communication between and inside programs. But, this can also refer to communication of the elements of programs like modules, components, or even classes or functions. Typically, this is related with communication between portions of the systems like frontend with backend or backend application with other backend apps. Api is a type of contract that specifies who can receive what and when by adhering to its rules. REST is now the style of API structuring that is most common. Rest, which stands for Representational State Transfer, is a set of guidelines for creating highly scalable, loosely linked applications. The remainder of the time, we should define urls using the plural form of terms and common data formats, such as JSON, remember about error handling and keeping our application secure.
PS
If you would like to know how to keep your code cleaner by following basic principles of functional programming click here.
Maybe you don’t understand recursion in 100%? We’re sure that after reading this article you will have no doubts!
Take care!
Patryk
Senior Software Engineer with over 7 years of experience and entrepreneurial background. Most often, apart from delivering good quality code on time, responsible for introducing good practices, teaching programmers and building team bonds andestablishing communication on the line of development-management. Privately Kākāpō and Wombat enthusiast, traveler and retired acrobat.