Book a Demo Sign up
Webinar on Public Knowledge Base: Portal Setup to Customer Delight - October 11, 2023 - Register Now!
Introduction to APIs

Introduction to APIs

Introduction to APIs

Category: API Documentation

Last updated on Sep 18, 2023

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 is 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 APIs (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:

  • 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.
  • Partner – these APIs are available to partner companies who want to integrate their services with another company. Access to the API is restricted and will have security features to prevent unauthorized access.
  • Private – these are internal APIs, used within an organization or within a specific system, which is not exposed to external users or other developers.

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

  • Simple – provides a single action; for example, in an API for a card payment system, enables you to create a card record.
  • 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 APIs 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 italicized, 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.

Check out how to manage and document APIs with Document360

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

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 provides 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!

Book A Demo
Document360

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 APIs 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 recognize 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 unauthorized 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 authorized 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 a 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 travelers, 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 authorization 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 authorized 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.

Example of an Accommodation Booking API

API example

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

Wrapping Up

APIs are ubiquitous in our modern, interconnected world, and almost all the systems and applications you use will be using APIs in one form or another.

So, whatever industry you are working in, it is likely that at some point in your career, you will need to be able to understand the API used by your organization.

An intuitive knowledge base software to easily add your content and integrate it with any application. Give Document360 a try!

GET STARTED
Document360
Mark Wentowski

Author

Mark Wentowski is an independent API Documentation Specialist with a 10 years of experience writing web-based, developer-to-developer conceptual documentation for webservices. He helps companies delivering SaaS products improve their API documentation by assessing their current gaps (i.e. consulting), and implementing a strategy that fills those gaps. He specializes in Migrating legacy documents in Print format to Markdown and HTML using scripts and static site generators.

Mark Wentowski

Jun 13, 2023

Public Knowledge Base: Portal Setup to Customer Delight