What Is an API? Introduction to Basics and Examples of APIs for 2022

What Is an API? Introduction to Basics and Examples of APIs for 2022

APIs work by allowing different types of software to communicate with each other. They make life a lot easier for programmers and provide a better experience for end users. APIs have several use cases and allow you to perform a variety of time-saving functions. For example, when you use your Google or Facebook account to log into a different service, you’re using an API.

In this article, we’ll explain everything you need to know about APIs, including:

What is an API?

API is an acronym that stands for “application programming interface.” An API is a pre-existing block of code that allows two different pieces of software to talk to each other. It takes a user’s input and uses it to tell an application what action to take. Then, it delivers the response back to the user.

As an analogy, let’s say you’re staying the night in a hotel and you decide to order room service for dinner. You call the receptionist at the front desk and tell them what you’d like to eat. They relay your order to the hotel kitchen. After the kitchen makes the order, the receptionist has a staff member bring the food to your room. In this example, the hotel receptionist is the API that allows you to send information (your order) to the kitchen and get a response (your food).

For developers, APIs can serve as shortcuts. They can plug an API into their code to do a common action, so they don’t have to waste time rewriting the code.

History of APIs

The idea to reuse codes to make computing easier was developed in the 1960s. Huge libraries were built to house actual tapes with codes. An operator would physically take the tapes and use a machine to combine them. Then, the operator would feed the combined tape into the computer. The computer would then perform that function.

The idea for modern-day APIs was brought up by computer scientist Roy Fielding. He detailed APIs in his dissertation, “Architectural Styles and the Design of Network-Based Software Architectures,” in 2000. Later that year, Salesforce first created its business API. Soon, companies like eBay and Amazon followed suit, and the software as a service (SaaS) industry was born.

As the internet has developed over the years, various types of API have been created for every type of function imaginable. We use APIs for everything from booking hotel rooms and shopping online to gathering research.

Types of APIs

There are a few different categories of APIs. However, when classifying an API, think about who the intended user is and where people will be able to access the API. Here’s a rundown of a few of the major types of APIs.

Private

Private APIs are only meant to be used by people inside an organization. A company might create a private API for its employees to gain access to a database of the business’s client information.

Here are a few functions a private API will usually have:  

  • Make a business’s internet applications and IT systems accessible to employees.
  • Build applications for clients using business IT systems and applications that are already in place.
  • Serve as an interface to a company’s backlog of information and resources for internal developers.

Private APIs can also be available to employees remotely or used for applications created for consumers who aren’t located physically within an organization. For example, a company might sell a piece of equipment with a subscription service. Tonal is an exercise machine that tracks and stores your workout performance.

A Tonal owner would use the app to access their information on the company database. Even though this app is available to both company employees and users, the actual API is still private because consumers can’t access or alter it.

Partner

Partner APIs are available to both a company and its business partners. Typically, a business partner will have to sign an agreement before accessing a business’s API.

Below are some common functions of partner APIs:

  • Integrate software systems among business partners.
  • Maintain communication among business partners.
  • Allow a business partner to make orders and track their status.
  • Allow business partners to see how resources are used and monitor user experience.  

Let’s say your company is partnering with a customer relationship management (CRM) organization to manage clients. You’d have to give the CRM company access to your customer database interface to integrate their software.  

Public

Public APIs are available to everybody. Any developer inside or outside a company can use them. Some remote APIs are open, while other ones are commercial. Open APIs can be used by developers free of charge without explicit permission from the API owner. Commercial APIs are usually offered through a paid subscription.

Here are a few of the possible functions of public APIs:

  • Help public developers generate software.
  • Generate income for suppliers through subscription services.
  • Increase brand awareness for the API supplier.

Composite

Composite APIs aggregate multiple APIs. Composite APIs are widely used in microservices. In a microservices architecture, every function on a website is designed to work independently. Developers use microservices so they can update small portions of an application at a time.

Let’s say you’re shopping for tennis shoes online. First, you’d do a search for the type of shoe you want on the e-commerce site. After finding a pair of shoes you like, you’d add them to your shopping cart. Then, you’d enter your information and check out. If the site has a microservices structure, each action would work independently and require a different API.

Rather than creating three different API calls to handle each request, the site’s developers would create just one composite API that would process each action and generate a response so you can buy the item.

Internal

Internal APIs are only available within a company’s demilitarized zone. These APIs are protected by firewalls. You can’t access them on the broader internet. In the past, fewer security measures were taken to protect internal APIs.

However, as more and more data breaches have been perpetrated by people within an organization, businesses have upped their cybersecurity protocols for internal APIs.

Here are a few functions of internal APIs:

  • Give developers within a company access to shared resources.
  • Allow companies to build apps fast without worrying about hacks from outside an organization.
  • Allow developers within an organization to use systems specified to their specific programming needs.

External

External APIs are available outside a company’s firewalls on the internet. While anyone can try to gain access to an external API, it’s not necessarily available to the public. It’s simply an API hosted on the internet. A user would use a passkey to gain access to the API from anywhere.

Below are a few functions of external APIs:

  • Allow users to access the API from anywhere.
  • Give companies the ability to use powerful third-party platforms outside their network.
  • Allow businesses to hire remote and contract developers to work on their networks.

If you’re looking for remote developers to join your team, Upwork lets you choose from the best independent developers with the front-end, back-end, and full-stack programming skills you need.

Common examples of APIs

APIs are used for everything from leveraging third-party developers to creating new revenue streams to accessing databases to communicating with external software components and webpages. In the next few sections, we’ll go over some of the main types of API connections.

Databases

Database APIs give app users the ability to request information from several different databases simultaneously using unified queries. Unified queries are data requests that can communicate with different types of databases (e.g., SQL, NoSQL, Hadoop). These databases may have any type of information a user is looking for.

When a user requests the API endpoint or hypertext transfer protocol (HTTP) URL, a browser API sends a message to a database server. The server, in turn, sends a message to the database API to search for the requested information. The database API then converts the data into an HTTP response and sends it back to be shown on the browser.

Here are a few examples of popular database APIs:

  • The Spoonacular API gives users access to all kinds of information about the food they eat. Users can learn new recipes, find nutritional information, and find out which foods are safe to eat for people with different allergies.
  • The GeoNames API helps users discover details about geographical locations. Users can find out things like the weather patterns and postal codes of locations all around the world.
  • The SWAPI (Star Wars API) helps users find a plethora of information about the massive Star Wars universe. Users can look up facts about different species, planets, and important events in the Star Wars canon.

Operating systems

Every operating system needs its own collection of APIs. APIs created for operating systems establish how applications on that operating system will use resources and offer services.

Web apps will communicate with operating systems (OS) to access resources and run on that OS. For example, let’s say you want to add a new photo from your iPhone to your Facebook account. An API for Facebook talks to the iOS API on your phone to add a new picture to your account. Your iOS API lets you know that Facebook is requesting access to your saved pictures and asks you to verify them.    

A company will typically create a software development kit (SDK) with a group of developer tools and APIs used in its operating system. Developers can download these SDKs to create apps that are compatible with a particular operating system.

Here are a few examples of API collections for operating systems:  

  • Apple’s iOS SDK helps developers create optimized apps to work with an iPhone’s touch-screen technology.
  • The Windows SDK gives coders access to all the newest development and formatting tools the company offers.
  • Android Studio has specialized SDK tools for developers looking to create apps for Google’s Android platform.  

Remote APIs

Remote APIs use resources that are located outside the device making a call. Any API that manipulates information or assets on an outside server is a remote API. That means all web APIs are remote APIs, but not all remote APIs are necessarily web APIs.

For example, a local area network (LAN) connects several computers in a general area (like an office). Often, one computer serves as a central server to the rest. Some LANs use network switches (devices that allow computers to connect offline).

Let’s say you’re a manager in an office that uses an offline LAN. You need to look up how many personal days an employee has taken this year. To find the information, you would use an API to access an employee database located on the central server/computer in the network.

Here are a few examples of remote APIs:

Web APIs

Web APIs allow clients (like applications and search engines) to communicate with remote servers through formatted queries (structured requests using a programming language like HTTP).

Let’s say you’re using an investing application on your phone to purchase stock. Even though the application is saved on your phone, all of the operations happen on an external server. When you tap the option to purchase a stock, the investing program sends a call to the server API, letting it know you want to buy stock.

Developers can also use web APIs to create new capabilities for their applications. An example of this is Google Maps API. It helps business owners share their company’s locations on the application so customers can find them.

Here are a few examples of popular web APIs:

  • The Product Hunt API helps users do things like find new technology products and follow trends.
  • The Etsy API lets developers create third-party applications on Etsy using things like payment processing and marketing tools.
  • The Kroger API gives users information regarding the grocery corporation, like product offerings, store locations, and customer data.

API protocols

API protocols, or specifications, are different forms of API design. There are several styles you can use to build APIs. Different protocols may use different programming languages or architectures to facilitate communication between applications.

SOAP

The simple object access protocol (SOAP) was created by Microsoft. SOAP uses extensible markup language (XML) to standardize the format for a message. XML language is designed to be readable for both humans and computers. A message using SOAP should follow an XML structure.

Here are a few code components a message using the SOAP API will have:

  • An envelope tag (route code) starts and ends the message.
  • A header has extra information needed for the message to be understood.
  • The body includes the coded request from an application or response from the server.
  • If the request isn’t understood, the body will contain a failure notice, with a reason the request couldn’t be processed.

By creating a standardized message format, SOAP provides developers with a clear and consistent way to keep track of information. But the process of labeling every message with so much data can be extremely time-consuming. A large amount of data can also cause slow loading times for applications and websites.

Today, SOAP is mainly used for certain projects that require a high level of security. The protocol’s web services (WS) security extension encrypts and locks messages. Locked messages can only be opened by users with security tokens. SOAP also stores previous requests on a server, which is necessary for complicated transactions.

Here are a few examples of APIs that use SOAP:

  • Paypal’s API uses SOAP to increase security and keep track of client interactions.
  • The Salesforce API has integration tools for developers who want to use SOAP.
  • The Postman API helps developers collaborate and create apps. It integrates SOAP and other protocols.

RPC

The remote procedure call (RPC) was the first and least complex API protocol. It can use one of two formatting languages to store, organize, and transmit data: XML or JavaScript object notation (JSON).

XML-RPC APIs take a long time to build. Developers started using XML in the 1990s. Because XML needs to be understood by both humans and computers, it has to be very structured.

However, XML is a markup language and not a programming language. It needs to be parsed (converted) into a programming language like Java or Python to send information. XML messages require a bulky XML parser to be converted.  

JSON-RPC APIs are simpler to construct. JSON is a lighter-weight markup language than XML that was created in the early 2000s. It’s designed to be understood by humans rather than machines. It also integrates with the JavaScript programming language. JSON messages can be parsed using a simple JavaScript command. Needless to say, more developers prefer to use JSON to develop RPC APIs.

In an API that uses RPC protocol, an application or a user sends a request to a remote server. The user’s call parameters (variables) need to be converted by a client stub (block of code), so they can be sent to the server.

The server stub translates the parameters, and the system completes the request. Then, the server stub converts the response and sends it back to the client. Finally, the client stub translates the response.

Here are some examples of APIs that use RPC protocol:

  • IBM’s APIs integrate with RPC protocol. They help create technology solutions for business.
  • The Travelport RPC API helps users make travel plans and learn about destinations.
  • The MyNetDiary API gives users access to food databases and helps them track nutritional information.

REST

The Representational state transfer (REST) protocol was developed in 2000. It was designed to be lighter than SOAP and allow a server to run faster. REST prioritizes resources and only uses a handful of hypertext transfer protocol (HTTP) verbs like:

  • GET: Retrieve
  • POST: Create
  • PUT: Update
  • DELETE: Erase

Each of these verbs responds to how the REST API will manipulate a resource. Each resource has its own uniform resource locator (URL) that can be plugged into a message on a REST API.

REST is more flexible than SOAP. While SOAP has a specific structure that must be followed for every message, REST simply advocates constraints that a developer should follow. However, these constraints can be broken in certain situations.

Here are some constraints suggested by the REST protocol:

  • The client-server autonomy constraint recommends that the user interface should stay intact when backend programming changes are made.
  • The uniform interface states that resources should have only one naming scheme, one data format, and one end-point (resource URL address) style to avoid confusion for users.
  • The layered system architecture constraint says a user talks to an application API, and the application talks to a server. The client doesn’t need to see the servers behind the application.
  • The stateless interactions constraint says a server shouldn’t store information from previous interactions.
  • The HTTP caching constraint says clients should be allowed to save information in a cache (storage on a software or hardware device). The use of caching lets users access their data quicker in the future.
  • The code on-demand constraint lets clients encrypt messages. The REST API gets the encryption key for the client. The server doesn’t know the encryption key. This constraint is rarely followed.  

The REST protocol doesn’t require nearly as much coding as SOAP. It has become the most common API protocol used today. While SOAP only uses XML language, restful APIs (APIs that follow the REST protocol) can be compatible with a number of languages like HTML, YAML, and JSON.

Here are some examples of restful APIs:

  • Twitter APIs have REST functionality that allows developers to work on the platform.
  • The Spotify web API lets users play and share music with each other and ask for data about musicians and songs.
  • Hubspot’s marketing APIs all use the REST protocol.

gRPC

Google created the Google remote procedure call (gRPC) in 2015. gRPC is an open-source (source code is accessible to everyone to use and modify), generalized version of RPC. gRPC lets developers identify any function calls. It’s not restricted to a small number of commands like the REST protocol.

The gRPC protocol uses protocol buffers or the Protobuf protocol to serialize and store data. Protobuf (Google’s cross-platform data format) is much more efficient than XML or JSON. Messages created using Protobuf are also compatible with several other programming languages.

Because gRPC is lightweight for a server and very powerful, it’s commonly used to manage microservices. Here are a few APIs that use gRPC:

  • TWIRP strives to make it simple for developers to create apps for the Twitch platform.
  • The Slack API makes it easier for Slack users to do things like get feedback from group members and automate workflows.
  • The Google Assistant API helps developers integrate voice requests with Google and Android apps.

GraphQL

GraphQL was created by Facebook in 2012. GraphQL is a query language that’s been designed specifically for APIs. Clients can use schema (database information structures) to request specific information.  

GraphQL is more challenging to learn than protocols like REST. Developers need to learn things like GraphQL niche operations to use it. And before GraphQL can be used with an API, backend programmers must define a schema for a database. Defining the schema can be time-consuming in the short term, but it saves time in the long run.

Because of its efficiency, GraphQL has become the standard protocol for creating APIs for mobile applications. Here are some examples of APIs that use GraphQL:

Apache Thrift

Apache Thrift is a scalable API protocol that was also developed by Facebook. Thrift is a user interface definition language (IDL) compatible with apps developed using several other programming languages, like C++ and JavaScript. It’s also a binary communication protocol that creates messages designed for machine-readable texts.

At its core, Apache Thrift is still an RPC framework. However, it’s much faster and more efficient than other API programming options, like SOAP or JSON-RPC, because it’s lighter weight on a server, and it creates messages that are easy for a computer to read.

Here are a few popular companies that use Apache Thrift for API frameworks:

  • Pinterest uses Thrift in several APIs to make them scalable.
  • Uber developers use the Apache Thrift framework for a number of APIs.
  • Crowdstrike is a cybersecurity company that integrates Thrift in its API design.

If you need developers to build APIs using various protocols, take a look at Upwork’s wide talent pool. Our platform allows you to find the best developers to help complete your projects.

API documentation

The API documentation provides instructions about how to use an API. Even an API with great functionality is useless if no one knows how to use it. Documentation helps users understand an API and drives the adoption of that API.

Good API documentation is easy to read and shows developers how to integrate the API with a variety of software types. It lays out things like API functions and return types.

Here are some reasons why API documentation is important:

  • It gives an API wider adoption.
  • It explains how to use an API and what integrations are possible.
  • It educates users about the full functionality of an API.
  • It gives users a better experience.
  • It reduces the amount of tech support you need to offer consumers, saving the company money and effort.
  • It makes onboarding new team members easy and reduces training costs.
  • It makes updating your API easier because you have a record of how functions fit together.  

Here are some things that a quality API documentation manual should have:

  • A quick start that lets users know things like the downloads they’ll need to use the API
  • Authentication data on how to access the API
  • An explanation of how to make calls using the API and a description of the returns and responses you’ll get back with examples
  • Examples of using the API with compatible code languages
  • Tutorials for integrating the API
  • Any SDKs that are accessible to help the API run smoother
  • An optional console where users can practice using the API

Static API documentation simply lays out information, but interactive API documentation can give users the opportunity to test out the API. Interactive documentation will have a human column with a written description of the API and a machine column where developers can practice making requests using the API.

There are several API documentation tools and solutions that can help developers and technical writers create quality technical documentation. They include:

If your company uses several APIs, you may want to invest in an API management tool like 3scale or IBM API Management to keep track of things like API creation and security.

Examples of popular APIs

Now, we’ll go over a few of the most popular APIs that exist today. We’ll talk about their functionality and show why they’re so commonly used.

Google Maps

Google Maps APIs can allow a company to integrate Google Maps on its websites and share its business locations with consumers. Here are a few of the main functions of Google Maps APIs:

  • Create custom maps.
  • Help users plan routes and figure out travel times.
  • Share business details and location with users.

The Google Maps API is so popular because it makes it easy for businesses to share address information with consumers on desktop and mobile apps. With the Google Maps API, developers make calls using HTTP and get returns back in structured XML or JSON.

Yelp

The Yelp API uses the GraphQL protocol to help users find entertainment, food, or anything else they might be looking for. Here are a few functions of the Yelp API:

  • Helps users find businesses in their area.
  • Lets users see reviews for local businesses.
  • Helps users access business information, like phone numbers, addresses, and what services a business offers.

The Yelp API is extremely popular because it allows businesses to share their information and ratings with potential consumers. Developers add endpoints to their apps to integrate with the Yelp API. The API uses HTTP requests to get data from servers and JSON exchange data.

OpenWeather API

The OpenWeather API allows users to get weather updates and geolocation data from locations around the world. Here are a few of the major functions of the free API:

  • Let users see weather forecasts.
  • Give users access to different time zones.
  • Inform users about weather hazards and things like UV rays and air pollution.

The OpenWeather API is popular because it gives users important information about weather that could affect things like their activities and travel plans. The OpenWeather API is a restful API that uses either JSON or XML to structure data. It has ample documentation that makes it easy for developers to use. Programmers can make calls on the API using HTTP or hypertext Transfer Protocol Secure (HTTPS) programming languages.  

Yahoo Finance

The Yahoo Finance API gives users information, updates, and news about the stock market, cryptocurrencies, and currency exchange rates. Here are some of the core functions of the Yahoo Finance API:

  • Let users track the price movement of stock or cryptocurrency by its ticker symbol (a series of letters that identifies security).
  • Give users access to financial news and developments in real-time.
  • Let users see historical financial data for securities.

The free Yahoo Finance API is known for being easy to use and integrate. Developers can use languages like Python and JavaScript to make requests on the API. The Yahoo Finance API uses JSON as its exchange format language.

Use APIs to enhance your business apps

APIs are great tools for bringing a greater level of functionality and usability to business websites and web applications. Using APIs can also save developers huge amounts of time writing code. The right APIs can help your company integrate great programs into its website and delight potential customers.

If you’re a business leader or manager looking for great developers to do things like integrating or creating APIs, take a look at Upwork’s selection of API developers. Upwork lets you view talent profiles of experienced workers from all across the world.

Projects related to this article:
No items found.

Author Spotlight

What Is an API? Introduction to Basics and Examples of APIs for 2022
The Upwork Team

Upwork is the world’s work marketplace connecting millions of businesses with independent talent around the globe. We serve everyone from one-person startups to 30% of the Fortune 100 with a powerful trust-driven platform that enables companies and freelancers to work together in new ways that unlock their potential.

Latest articles