Everything you need to know about APIs

Everything you need to know about APIs

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

Screenshot (4).png

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).

Screenshot (2).png

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.