As easy as designing an API could seem, it could also be tricky if you don't know the foundation. This article would shed light on what you need to know before designing an API. Let's dive right in!
What is an API?
Application Programming Interface (abbreviated as API) is a software intermediary that allows two applications to communicate with each other.
Example of an API in a real life scenario
Imagine going out to have lunch in a restaurant, you pick up the menu and pick whatever choice of food you'd like to eat. Now, you communicate the choice of food you want to the waiter, in this scenario, the waiter is an API because he/she takes your order. The waiter goes and communicates this choice to the kitchen ( in this case is the "part of the system") which then processes the order and communicates the result back to the waiter. The waiter, then, delivers the final message back to you.
Another example of an API would be using an application like "Whatsapp" to send messages, the application uses the internet to send this message and also retrieves the incoming message and displays it to you. This is a typical example of an API
API as a layer of security
You tell the restaurant what you want to eat, they tell you what they require in exchange, and you get your meal at the end. The process of making the meal is never disclosed to you.
Now, think about this same scenario but with computers. Your computer's data is never fully exposed to the server, and likewise, the server is never fully exposed to your computer, instead, communication is made by sharing only what is necessary.
What's a web API ?
As the name implies, a web API is an API that can be accessed via the internet using the HTTP protocol. It's a framework for creating and developing HTTP-based RESTFUL services. Different technologies, such as java, ASP.NET, and others, can be used to create the web API.
A web server or a web browser can use a web API. Web API is essentially a web development idea. It is restricted to client-side Web applications and does not include information about a web server or a web browser.
Types of web APIs
Open APIs (also known as Public APIs)
Any outside developer or business can utilize a public API because it is open and available. A company that develops and offers a public API will have a business model that includes sharing its applications and data with other companies.
They may or may not require registration or the use of an API key, and they may or may not be totally open. External users (for example, developers at other firms) can access data or services through them.Internal APIs
Internal APIs, as opposed to open APIs, are meant to be kept secret from outsiders. They're used to share resources within a corporation. They enable several teams or departments of a company to use each other's tools, data, and programs.
Security and access control, an audit record of system access, and a consistent interface for integrating numerous services are just a few of the benefits of using internal APIs over traditional integration strategies.Composite APIs
Composite APIs are made up of two or more APIs that work together to create a series of connected or interdependent activities. Composite APIs can be useful for addressing complex or closely linked API behaviors, and they can occasionally outperform individual APIs in terms of speed and performance.
Partner APIs
APIs accessible to business consultants are referred to as "partner APIs." They aren't accessible to the general public and require special permission. Partner APIs, like open APIs, are the peak of the glacier since they are the most visible and utilized to communicate outside of the company's limits.
API protocols and architectures
SOAP
SOAP (simple object access protocol) protocol is a well-known online API protocol. It's meant to be flexible, agnostic (able to work with a variety of communication protocols, including HTTP, SMTP, TCP, and others), and self-contained (it allows for any programming style)
REST
REST is a collection of architectural principles rather than a protocol like other web services. The REST service must have specific properties, such as simple interfaces, which allow resources to be recognized quickly inside the request and resources to be manipulated using the interface.
JSON-RPC and XML-RPC
An RPC is a protocol for making a remote procedure call. XML-RPC calls are encoded with XML, whereas JSON-RPC calls are encoded with JSON. Both protocols are straightforward. A call can have several parameters and only expects one outcome.
8 Tricks you must know before designing an API
1. Follow a coding standard
This may sound simple but can be very difficult to keep up with sometimes. The best APIs are the ones that are very easy to understand. This is one of the main clues that tell if an API is well designed or not.
Stick to the same casing, whether you choose to use the camelCase or the kebab-case or you might just be the snake_case type.
Stick to the same HTTP status codes based on the type of response, for example, 201 status code returns a successful creation of a new resource
Stick to the same HTTP methods for the same type of actions, for example, get when trying to fetch a result from the database
2. Adopt logical HTTP status codes
200 OK for request succeeded
201 for request successful and a new resource was created
400 for a bad request due to client error
401 for unauthorized request
500 for internal server error
3. Adopt logical HTTP Methods
POST for creating new resources
GET for retrieving resources
DELETE for deleting resources
PUT for applying full updates to a resource
PATCH for applying partial updates to a resource
4. Use simple names that are easy to understand
For example,
GET /students - Retrieves student details
DELETE /students/{id} - Deletes student details
PUT /students/{id} - Updates student details
5. Use SSL for security
Secure socket layer (abbreviated as SSL) is critical for security when designing APIs. As a result, your API will be more secure and less subject to malicious attacks.
Other security considerations to consider include keeping communication between the server and the client confidential and ensuring that anyone using the API only gets what they ask for.
The "s" in HTTP is the clear distinction between an API that runs over SSL and one that does not:
SSL is used on https://myblog.com/posts.
SSL is not enabled on http://myblog.com/posts.
6. Adopt JSON as the format for sending and receiving data
Accepting and replying to API requests in the past was primarily done via XML and even HTML. However, JSON (JavaScript Object Notation) has mostly replaced XML as the standard format for delivering and receiving API data.
Because JSON was designed specifically for it, JavaScript offers an inbuilt capability to parse JSON data using the get API. However, every other programming language, such as Python or PHP, now includes capabilities for parsing and manipulating JSON data.
7. Return a list of created resources when using POST
After creating a resource with a POST request, it's good practice to return it. This is significant because the new resource will reflect the current state of the underlying data source and will include more recent data (such as a generated ID).
8. Choose PATCH requests over PUT requests
PATCH requests, as previously stated, should apply partial updates to a resource, whereas PUT requests should completely replace an existing resource. It's always good to build updates around PATCH requests, mostly because allowing any field to be altered without constraints is quite risky.
Don't forget to like and comment, if you enjoyed this article. Bye for now.