What Is an API?

API is an acronym that stands for “application programming interface,” and it allows apps to send information between each other. While there are numerous protocols and technologies involved, the underlying purpose of APIs is always the same: to let one piece of software communicate with another. 

APIs (sometimes described as web services) work in the background whenever two applications interact, from sending instant messages to making purchases through online ticketing systems. This all happens behind the scenes, making user experiences effortless.

Developers use APIs to enhance their products by accessing another company’s data, software, services, or code, thereby providing additional features while saving time and money.

APIs create conveniences for end users and developers alike—but there’s more to the story than that. In this post, we’ll cover how to use an API, explore the different types of APIs, guide you towards choosing the right APIs for your organisation, and offer tips on successfully building your own.

How do APIs work?

API software lets the components of two applications talk to each other using a set of simple commands. Essentially, APIs are messengers that deliver requests and return responses between applications. 

In each interaction, there’s a server (the app providing the resource) and a client (the app making a request). If the server can do what the client has asked, then the API will return the relevant resource. 

If the client requests a resource that doesn’t exist on the server or that the client doesn’t have permission to access, the API will instead provide an error message. By only providing data that has been made available to external users, APIs enforce selective access control to the server.

This is all quite abstract, so let’s bring it down to earth with an analogy. Imagine you’re at a restaurant, ordering off a set menu. You, the client, place your order with the waiter. The waiter takes your order to the kitchen, just like an API call would send your request to a server. If the kitchen is able to prepare your meal, then the waiter will return with your order; similarly, if the server can grant your request, then the API will provide your resource.

Most importantly, you don’t need to understand what the chef does or even know how to cook. You just need to know how to read the menu and speak to the waiter. And once you understand how to order from one menu, you can order from any menu. Common patterns and practices are often used between unrelated APIs—like Twilio and Github—which means developers can adopt them easily.

Online booking services that aggregate a number of databases show this dynamic in action. Skyscanner, for instance, interacts with each airline’s API interface to request booking information, like ticket prices and baggage options, without requiring you to know how to connect: the API takes Skyscanner’s request to each airline and returns the relevant data in response. Other examples of APIs in action include Fandango and StubHub, which make requests to movie theatres and ticket vendors to the same effect.

What are the most common API commands?

Most API users want the server to perform basic functions. The four main kinds of API requests are:

• GET: To retrieve data
• PUT: To update existing data
• DELETE: To delete existing data
• POST: To do everything else, including creating new data

Web APIs generally use HTTP to transmit these request messages, which provides a structure for communications between the server and client. While request messages are typically written as URLs, response messages often take the form of JavaScript Object Notation (JSON) files. This is because JSON presents API data in a way that’s easy for us to read and use.

What are the main types of APIs?

There are three types of APIs that organisations can use or create, which we’ll talk about below.

Private/Internal APIs

Private APIs are only available internally within an organisation. While developers working for the company can use these APIs, third-party developers cannot. As these APIs aren’t documented in publicly accessible software development kits, they’re often completely unknown to the public. Most analysts believe nearly all APIs are private or internal.

Partner APIs

Partner APIs are shared externally with business partners of the organisation. Usually these are used for creating deep integrations, sharing sensitive information or functionality, or accomplishing things that each organisation could not individually. For example, traffic app Waze uses APIs to exchange data with local government agencies and other partners about road closures, accidents, and other factors that impact traffic.

While partner APIs are more open and available than private APIs, they likely have tighter controls over access and documentation. Unless you work with one of the organizations involved, you may not even know the API exists or how to request access.

Public/Open APIs

Public APIs, like those used for Facebook and Google’s social login solutions, are available for third-party developers to use. Getting access to these APIs could be as simple as registering on the provider’s website, completing an application and approval process, or even paying a subscription fee. It varies between providers and may depend on your intended purpose and volume of activity.

Private, partner, and public APIs each provide access to an organisation's resources—but how they open that access and to whom depends on their target users and intended integrations. 

What are the benefits of using APIs?

Whether you use APIs to standardise procedures or to build new features from another company’s resources, they bring several notable benefits.

• Increased speed to market: Using APIs gives your workforce a uniform set of protocols for how apps interact. This helps to streamline the way you work, allowing you to easily test features and functionality—and validate your value props more efficiently. In addition, APIs create consistent methods of exchanging data and capabilities across the company, and improve transparency as a result.
• Deeper focus on your strengths: By reusing software components via APIs, developers don’t have to repeat work that’s already been done. Instead, they can focus on creating new tools and features that align with your company’s unique offerings and provide further value to users.
• Freedom to outsource complexity: Your developers can't be experts at everything. An API enables your team to use another’s expertise (whether they’re down the hall or across the globe) and focus on your company’s own systems.
• Better user experiences: Your development team might be top notch, but they can’t anticipate or build from scratch every feature that customers want. By using external APIs, you can optimise how your app or product performs and broaden what it can do. This is how you create first-class user experiences—at little cost.

What APIs should I use?

The value of using APIs is pretty clear cut, but the more difficult task is choosing the right ones for your organisation. Keep the following factors in mind when considering your options:

• Feature relevance: Above all else, know exactly what features you need. Similar APIs may well provide different features and support, so look at each potential option and make sure it meets all of your requirements.
• Documentation and interface: Support documentation with clear explanations and useful examples is a must. When reviewing the documents, look for naming conventions that are clear and consistent.
• Usage limitations: Many APIs employ limits, especially those with public-facing data. This is generally to prevent abuse by API customers or to encourage subscription upgrades. If you’d rather live without the overhead of managing your API usage, see if any competitors offer higher or non-existent limits.
• Acceptable use policy (AUP): Make sure your idea and use case is supported and allowed by the API you select. In general, follow your local laws and review each AUP to confirm that your product can launch and grow.
• Language support: Ideally, the provider will give API programming support in the code language that you’re using. This will save a great deal of time when it comes to development, as the alternative means switching to a supported language.
• Community: Sometimes, things don’t go to plan. An active, helpful community is a good sign that you can get the support you need. Take note of the API provider’s reputation for answering queries.

Why should I build an API?

Creating an API and sharing it externally is a good idea for several reasons. For one, thousands of companies have monetised their APIs, turning them into significant revenue streams. In MuleSoft’s 2020 Connectivity Benchmark Report, IT leaders reported that an average of 31% of their company’s revenue comes from APIs, so there’s a lot to gain financially from going public.

What’s more, by sharing an API, you’ll build a network of users who rely on your API code and data. This encourages users to adopt other parts of your platform, expanding your customer base and increasing loyalty.

If you're thinking about building your own API, our developer resources and guides can help you design certain types—though here are some things to keep in mind more broadly:

REST vs. SOAP

APIs follow one of these two structures to standardise communication and data exchanges between web services. Compared to SOAP (Simple Object Access Protocol), REST (Representational State Transfer) is widely considered the better option as it is easier to use and imposes a less rigid structure with lighter coding requirements. For more information, check out our guide to securing REST APIs.

SOA vs. microservices

These are two competing structures for API development. While service-oriented architecture (SOA) takes advantage of reusable software components to power enterprise-wide developments, microservices are typically used to build individual applications to be agile and scalable. The primary difference between the two comes down to implementation, not goals. SOA generally leverages SOAP and its complexity while microservices leverage REST and more modern protocols. Think of microservices as the next iteration of SOA with many lessons learned and applied.

GraphQL

This is erroneously thought of as a replacement for REST—but that’s like thinking Netflix is a replacement for your internet provider. Put simply, GraphQL is a process and set of patterns for making more specific requests for data, built on top of many common REST patterns. In that sense, REST and GraphQL actually work together. 

In general, REST by itself returns a lot of information which you may not need. GraphQL, on the other hand, trims that down to just the data you need. When used well, it can be more efficient and lead to higher performance.

Security

As APIs attract a range of external users, you need strong security measures in place to stay protected. We recommend building your API in line with the OAuth 2.0 security framework. Okta’s API Access Management additionally fortifies your authentication and authorisation support, protecting your organisation and API users from any threats.

However you decide to build your API, security is a must-have. Learn more about Okta API Access Management and check out our guides to API gateways and API security for more advice.