API fundamentals

What’s an API? API fundamentals – IBM Developer

API stands for application programming interface. An API is basically a set of definitions and protocols that enable two applications to talk to one another. APIs are the connectors that enable most of the communications between the web applications, or apps, that we use today. For example, if you use apps on your phone to check the weather, or send a message to friends, or to find the nearest cafe, you’ll be using APIs without even knowing it.

APIs work by communicating with, and exchanging data between, other systems. They act as the messengers between us, the users, and the backend systems, allowing us to retrieve the data we want, when we want it. Let’s take a familiar example. Say you’re going to stay at a hotel, but you’ve not been there before, so you want to use a navigation app to get there. You input some details about the journey into the app, like the destination address, whether you’re going by car or by public transport, and any route preferences. Now, for the app to provide you with a complete navigation picture, it will check several different services, such as GPS data, weather information, public transport timetables, route delays, amenities, and so on. The navigation app will interact with all of these services by using APIs.

API basics

In software terms, APIs are a set of functions and procedures that allow application developers to create apps that use the data and features of other services and applications. APIs give developers a toolset that they can use to create their apps.

There are three main types of APIs:

• Open APIs, which are publicly available with minimal restrictions to access them.
• Partner APIs, which need specific access rights to be able to use them and are typically exposed via an API developer portal.
• Internal APIs, which are hidden from external users and only exposed by internal systems. Typically, these are exposed via an internal API developer portal to enable authorization to the right set of APIs.

There are also two different ways that APIs can be implemented:

• Simple APIs, which are available separately.
• Composite APIs, where multiple data or service APIs are combined together, allowing developers to access several APIs at a time. For example, you’d implement composite APIs in a microservices architecture, where a user needs information from several endpoints to perform a single task, like the navigation app example we described previously.

Types of API protocols

To be able to use APIs effectively, developers must adhere to a common set of rules, or protocols, when making API calls. The term API call simply refers to the process of communicating with an API; in other words, an API call is when data is sent to and retrieved from an API endpoint.

There are three main types of API protocols:

• REST. REST is short for Representational State Transfer and is a web services API. It provides a uniform interface, where a client and server communicate with one another via Hypertext Transfer Protocol (HTTP), by using Uniform Resource Identifiers (URIs), the common Create, Read, Update, and Delete (CRUD) operations, and most often JavaScript Object Notation (JSON) conventions for data exchange.
• SOAP. SOAP is short for Simple Object Access Protocol and is another type of web services API. SOAP APIs have been used since the 1990s, but the protocol is stricter and more heavyweight than REST, so it isn’t used as much in modern API development.
• RPC. RPC is short for Remote Procedural Call and is the oldest and simplest type of API protocol. RPC is a request-response protocol, where a client sends a request to a remote server to execute a specific procedure, and then the client receives a response back. However, RPC APIs are much more difficult to maintain and update than REST APIs, so again RPC APIs aren’t used as much in modern API development.

REST APIs have become the preferred standard for building apps that communicate over a network. However, there is a new data query and manipulation language for APIs that is rapidly gaining ground called GraphQL. GraphQL provides a different approach to API development, where the client, or app developer, has much greater control over what data is returned.

Styles of API development

These days there are many different technologies that you can use for developing APIs, such as REST, OpenAPI, HTTP, gRPC, GraphQL, and Kafka. Which technology you choose really depends on what style of API that you want to develop and your overall business strategy and constraints.

Here are the five main styles of API development:

• Tunnel. In this style, the API is a collection of functions that can be called remotely. A common technology used in this style is Remote Procedure Call method. The tunnel style is focused on making specific computer functions available. This is a popular style; for example, gRPC is an open source remote procedure call framework you can use to develop APIs.
• Resource. In this style, the API is a collection of resources that can be interacted with. This style is likely the most popular style for public APIs, enabling resources like products, customers, and other data to be accessed. A common technology that’s used for this API style is HTTP that calls an API that’s been written following the OpenAPI specification. (The OpenAPI specification defines a standard, language-agnostic interface to RESTful APIs.)
• Hypermedia. This style is an enhancement of the Resource style. In this style, the API is a collection of interlinked resources, which is very much how web apps are delivered. Similarly, this style often uses HTTP calls to an OpenAPI-described service, with the difference being that the data also includes controls to link the resources together.
• Query. In this style, the API exposes a structured data model that can be queried and updated by using a generic query language. This style is usually used when you have a large amount of data, where the API needs to query the dataset and return just the data needed for that query. A very popular example of a technology that uses this style is GraphQL, as noted previously. GraphQL is a very flexible query language that allows you to ask for specific sections of a large data model, thereby enabling API developers to interrogate large amounts of data much more efficiently.

• Event. In this style, the communication pattern is reversed, and the API listens for events instead of asking for information. In most cases with event style APIs, the API works in what is called a publish/subscribe (pub/sub) model, where API consumers listen out for events that they’ve subscribed to. For example, your API might listen out for when a particular product is bought, and then take an action based on that. One of the most popular event style technologies is Kafka.

Once you’ve chosen your development style, then you can look for the technology that’s the best fit. There’s no ‘one size fits all’ in API development. You should make a considered design choice that fits your business, and invariably that technology will evolve over time.

Benefits of API development

Now, let’s look at why businesses use APIs. Although there are many varied reasons to develop APIs, here are our top four:

• Speed. Having a library of reusable APIs speeds up application development and ongoing app evolution.
• Security. APIs enable you to securely expose systems of record and business logic to mobile, web, and cloud apps.
• Socialize. Publishing APIs expands your brand reach and enables you to tap into broader developer and partner ecosystems to drive innovation.
• Monetize. Enable new business channels by charging money for the use of, or rate of use of, the APIs that can access your data and algorithms.

Summary

In this article, we covered the basics of API development, discussing API protocols and styles of API development. We also covered the key benefits of developing APIs.

In the modern world, APIs have become a valuable business asset in themselves. This is what’s commonly referred to as “the API economy.”