Introduction to APIs

What is an API?

An API (Application Program Interface) provides a method for connecting between different systems or software programs. An API provides users with access to a resource, such as a chunk of code or a module, which other systems can connect to in order to access functionality within a program or system.

API are used in almost all contexts in our daily lives, such as when using our mobile phone apps, when paying for something over the internet, when connecting to other devices or services, and when connecting to devices that are part of the Internet of Things (IoT).

Developers create APIs when they want to make software modules or code classes available to other developers for their use in their own programs. Companies provide APIs to other companies and users, to support access to services and functionality.

There are both internal API (i.e., used within a system by different software components to communicate with each other) and external or remote API (where different systems can connect to each other to request and consume resources). An API can also be classified based on its intended use:

1. Public – these APIs are available to use by anyone with the skills to connect to them. Examples include Google Maps API and the Open AI Standard.
2. Partner – these API are available to partner companies who want to integrate their services with another company. The access to the API is restricted, and will have security features to prevent unauthorized access.
3. Private – these are internal API, used within an organisation or within a specific system, which are not exposed to external users or other developers.

The API may also be classified based on what it does:

1. Simple – provides a single action; for example, in an API for a card payment system, enables you to create a card record.

2. Composite – may combine several functionalities in a single API call; for example, in an API for a card payment system, enables you to create a card record, load the card with funds and activate the card.

APIs can also be classified based on whether they are a paid for service or free to use. Open source API are free to use without payment. Other APIs require the user to pay to access the service.

The terminology around APIs may be intimidating if you are not familiar with them.

Look out for words that are italicised, which indicate terms that you will commonly hear in the context of APIs. You should understand what they mean; for details, see the Glossary section at the end.

API Technology and Terminology

The APIs most of us are familiar with work over the open internet using HTTP as the communication protocol. In addition, the API uses a separate protocol or standard to facilitate the communication and encode the message. The two main types of API are SOAP and REST.

• SOAP is a common API used in legacy systems. It provides messages in XML (eXtensible Markup Language) format. These API are used in many banking and financial systems.
• REST is a set of RESTful principles designed to enable modern API provided over the internet. It typically provides messages in JSON (JavaScript Object Notation) format. It is now the most commonly used API, used by over 75% of API.

For more comparisons of the use of SOAP vs REST, check out this article.

The API connection will typically also be a secure (HTTPS) connection, using SSL (Secure Socket Layer) or TLS (Transport Layer Security).

Modern API also provide additional security features to ensure that only authorized users can access the API resource. Examples include the use of special Oauth Bearer Tokens or encrypted API keys. A valid Token or Key must be attached to the API request. This is checked by the remote system before allowing access to the resource

Also, Check out our article on Internal vs External API and API lifecycle management.

Ready to take your API documentation to the next level? Book a demo with Document360 today!

How do APIs work?

Developers of a program or system may decide to expose some functionality to external systems or users via API. In their code they make these API public, so that the program resource can be consumed by other applications or systems.

The remote or external system sends a request to an API endpoint (this is similar to a URL in format and identifies a specific location or resource); the API endpoint is also referred to as a URI (Uniform Resource Indicator).

The API request (or API call) must be to a correct API endpoint. It must be in the correct format and contain valid fields and permitted field values in order for the remote system to be able to recognise and process the request.

Typically, when connecting to an external system offered by a third party company, some form of security and user authentication will be in place to prevent unauthorised access to the resource. A username and password, security token or bearer token (access token) may need to be included in the request in order to authenticate the user and access the resources on the remote system.

The resource will enable the requester to do something, for example: get a piece of information about an account, update information in an account, post information to create a new account or delete an account. In API terminology the verbs GET, PUT, POST, UPDATE and DELETE are called HTTP methods and are used to indicate the type of action requested from the API endpoint resource.

If the remote system has any problems processing the message (for example, the user is not authorised to access the resource, the requested URI cannot be found or the content of the message is not in a valid format), it will return an error message (or throw an error).

If the request is valid, the remote system will typically return an OK response, together with the result of the request. This response message is referred to as the API response.

The system that requested the API resource is now able to process the response.

Example

Let us take closer look at a simple example of an API used by a mobile phone app for an accommodation booking service.

1. The user enters the location and dates of travel they are interested in, and other information, such as their budget, the number of travellers and specific room requirements.
2. The mobile app prepares the message content (the payload). The payload will include the message body (all the fields containing values) and a message header (containing information about the format of the message and other metadata such as any authorisation parameters).
3. The mobile app sends the API request to the API endpoint – a URI on a remote booking management system.
4. The remote system receives the request and first checks that the requester is authorised to access the service, the resource is available and the payload format is valid.
5. It looks in its database for available rooms that meet the details provided in the request. It returns this information to the requesting mobile app.
6. The mobile app receives the response and displays the results to the user.

Why APIs are so valuable for Business today?

APIs are essential for businesses that want to grow. Below are some of the benefits:

• Simplify and expedite their market entry tactics
• Improve client interactions
• Increase operational agility and speed
• Create and seek new income, market, and distribution channels
• Develop new revenue streams or expand existing ones
• Increase the reach of your brand
• Improve efficiency and open innovation through external development

Click here to read more