New
{New}  See what’s new with MongoDB 6.0 — and why you’ll want to upgrade today >>

APIs Explained

An API or Application Programming Interface is a messenger or a middleman that lets computer programs securely access data from one another. A very common example of an API is a flight booking website that compares prices of flights from multiple airlines. The application requests data from multiple third-party APIs, which in turn connect to the actual data source (like databases). Once the API passes the response to the requesting application, the client user interface (UI) displays the information in a single view.

What is an API?

An API is not a database or web server. However, it provides secure access to both. When an application or client requests some information (data) to the API, the API redirects the request to the appropriate source and passes the received response to the client.

What is an API What API is and what does it do


So, what exactly is an API?

Interface is a core object oriented programming principle (OOP) used by many programming languages. Interface hides the implementation from outsiders (i.e., third-party applications and services), but still lets them use functions from an application. So, if you want to use a functionality, you’d know what the method does, but you wouldn’t know how the method works! The interface in an API is very similar—you hide the internal workings of your program by exposing only a part of the functionality through the API.

Why is it helpful?

By exposing an API, you provide a protocol that other programs can use to communicate with your app.

Let’s say you want to build an app where users can book slots for playing basketball, based on court availability. Since basketball is an outdoor sport, you want to display the weather so that it's handy for customers to make an informed booking. If there is already a weather application that displays weather based on your location and time, it’d save a lot of your effort building another one.

Now, if the person who created this weather app exposed a public API (say the method name), you can use their functionality as it is and get the data for your app users!

what is api? Example to show an API

How does an API work?

Companies can create APIs for their internal use or to share with the public. For example, social media plugins and programming language APIs are used by developers and web users. Any individual can create an API to share their content with more people. There is no front end of an API and the requests are usually sent through a web server over the internet.

There are different types of APIs.

The most commonly used web APIs follow the REST (Representational State Transfer) architecture, where requests and responses are delivered via the HTTP protocol.

how an API works How applications use API to exchange data


The API works as follows:

  1. The client places a request from their device, using the HTTP GET, PUT, POST, or DELETE methods. The request is sent via HTTP to the URI (Uniform Resource Identifier). The requests include the request method, headers, and body—for example, in XML, JSON, or other formats.

  2. If the request is not valid, the API will not call the program but return an error.

  3. If the request is valid, the API makes a call to the required service.

  4. Once the API receives the response from the service, it sends the response back to the requesting application (client) via HTTP.

The different types of APIs

There are four basic types of APIs:

types of APIs Various types of API like public, private (internal), partner, composite

Public APIs

These APIs are made to be accessed by the general public, like individuals, entrepreneurs, developers, and third-party systems. There are some minimal restrictions to authenticate and authorize the users using API key or OAuth. Some APIs don’t have any authentication at all. Most of the APIs are built as public, so that many people can benefit from them—for example, programming language standard library APIs, Google Maps, and OpenWeatherMap.

Internal API

Internal APIs are not publicly exposed and can provide access to sensitive data. They are used by organizations for their own business purposes—for example, an HR portal, where HR and managers can access employee information and update it.

Partner API

This type of API is conditionally shared to certain business partners or organizations. These need proper authentication and access control, and only those with valid authorization credentials should access the APIs. For example, a merchant can provide a partner API to certain partners to see potential marketing opportunities, events, earnings, and offers.

Composite API

In a composite API, the client requests multiple resources with one API request. For example, in a web page for a product, you need to display both the details for the product and the customer reviews for it. Usually, you will need to send two API requests—one for the details and one for the reviews. If you’re using a composite API such as GraphQL, you can fetch both the details and the reviews by requesting a single API endpoint.

What are some examples of APIs?

With the concept of reusing pitching in more, APIs are finding use everywhere! From weather apps and Google Maps to YouTube and Facebook video plug-ins, you can find an API being used in almost every web application today. Some day-to-day examples of APIs are:

Flight booking

Most of the time, we want to compare prices of different airlines and then book the cheapest one. There are many websites that collect data from multiple airlines and display it in a single view. These websites use APIs of the airline (external) system to access their database and get the required information.


flight booking api example

Example of web api where a flight booking site gathers data from multiple airlines and displays it in one view

Google Maps

Google Maps is a very advanced app that not only shows directions to a place, but also live traffic updates and alternate routes. Cab companies like Ola and Uber, and food delivery companies like Zomato, use the Maps app, rather than creating a new map functionality from scratch.


Google maps API

Uber, Ola and many other apps use Google maps API for users to track cabs

Social media APIs

You may have seen YouTube videos or Facebook posts embedded in a web browser, an article, or an app. Same way, Twitter, Instagram, and many other social media handles can be integrated within an application or browser using their APIs.

Screenshot of the Facebook GraphQL API Explorer.

Facebook offers a GraphQL API to get data into and out of the social network..

Single authentication

Many new websites provide an option to log in using your Gmail or Facebook credentials, and pick up your public data from their database. They use APIs provided by these companies to authenticate you. This saves you time as you don't have to register for every site or app you use, and companies can use the same data that you provided to Google or Facebook.


sign up using existing id

Google and facebook provide apis so that users can register to new sites using the same id

Third-party payment apps

The use of digital payment options like Google Pay and PayPal has ensured secure transactions without having to type any sensitive account information. These retail apps connect to payment systems through APIs to complete the payment process.

Retail sites redirecting to payment gateway.

Websites that use digital payment option connect to third-party payment apis for secure payment

The different types of API protocols

There are different API protocols, the most common being REST, which is an architectural style, that uses HTTP for sending requests.

API protocols

There are many API protocols, like REST, SOAP, XML-RPC, JSON-RPC and GraphQL

REST API

REST is an architectural style for building APIs. The architecture defines a few constraints and principles:

  • It’ is client-server based, where the client handles the front end and the server handles the back end independently.
  • It defines a uniform interface.
  • It’s stateless, as each request is independent of any other request and should contain all the necessary information.
  • Responses can be cached for further processing, if needed.
  • It allows on-demand code in the form of scripts and applets, reducing the amount of code that’s pre-implemented.
  • It follows hierarchical structure, so that only the adjacent layers communicate with each other.

These guiding principles make REST very fast and efficient to use. Commonly used REST API methods are GET, PUT, POST, DELETE, HEAD, TRACE, and OPTION.

Another common API is the WebSocket API, which uses JSON for data transfer and supports two-way communication between client and server.

RPC-based APIs

Program APIs are based on RPC (Remote Procedure Calls), where calls made to a remote system appear to be local calls. Some protocols based on RPC are:

  • SOAP (Simple Object Access Protocol): SOAP uses XML syntax to transfer data. SOAP has strict rules and is very secure. SOAP is good for data transfer between applications that are written in different languages or are in different environments. SOAP uses SMTP and HTTP protocols and transfers data using WSDL.

  • JSON-RPC: JSON-RPC uses JSON syntax for transfer. It’s fast, light-weight, and flexible and independent of transport protocol.

  • XML-RPC: This is the same as JSON-RPC but uses XML for data transfer. It’s light-weight and flexible compared to SOAP.

GraphQL

GraphQL (Graph Query Language) is a fast, stable, and flexible query language and runtime. With GraphQL, developers can construct requests to pull the necessary data from multiple sources in a single call. The response contains only what is required, which makes GraphQL light-weight and simpler than SOAP. Organizations like Facebook, GitHub, Netflix, and PayPal are adopting GraphQL to simplify the response and have a single entry point for data access.

What languages are APIs written

Any of us can write an API, provided we know which languages we want to write the API in. Some common languages are Java, Python, PHP, Ruby, .NET, C++, and JavaScript. These languages are easy to learn and use, and suitable for even new software developers.

Advantages of APIs

APIs have many benefits, like code reuse, saving time and cost of development. Some prominent benefits are:

  • Easy sharing and redistribution of reusable code: APIs can be shared with any number of people and have a wider reach.

  • Mobile and in-app integration: By using APIs, companies can integrate their content and services into their apps, without downloading or creating new infrastructure or code.

  • Saves development time: As content can be reused within and across organizations, teams can save a lot of development time by reusing the content created by someone else.

  • Automates business processes: Having APIs for already existing tasks and modules helps businesses use them without having to test them again and again. They also don’t have to worry about the technology being used to create the APIs.

MongoDB Atlas and APIs

MongoDB provides APIs and drivers for a dozen programming languages, along with extensive documentation. MongoDB’s unified query API lets you seamlessly work with any data type, like time series, arrays, and geo-spatial data.

MongoDB Atlas API lets you access your cloud data programmatically with just a few configurations. With the new Atlas Data API, you can easily build data-centric microservices, or integrate with third-party services—tasks that were earlier considered tedious.

FAQs

How do you create an API?

You can code API in any language of your choice. Here are the steps to create an API:

  • Define the purpose and target users for the API.

  • Decide the architecture for the API, like SOAP or REST, depending on your requirements. The API should be secure, scalable, and easy to integrate and test. If you want high performance and speed, REST would be a good choice, but if security is more important, you can go for SOAP.

  • Write the API. Start with the basic functionality and iterate to add more features gradually. Handle exceptions properly, define all the HTTP response codes, and build an endpoint for the API to receive the requests.

  • Check for the API performance. Implement pagination and caching if needed by the application.

  • Write clear documentation—for example, endpoint, supported request and response, exceptions, classes, interfaces, and methods. There are several tools to do this for you.

  • If you’re building a public API, then at some point, you may want to expand its features. In this case, it's a good practice to add a version.

  • Test your API. It’s important to understand the load and whether the API is able to handle the traffic. Use real-world data to check for performance and load testing.

  • Publish your API using the API gateway and monitor the performance.

Is API a technology?

API is not a technology. It’s an interface that lets developers reuse a functionality already written by someone, rather than creating the same functionality again. An API acts like a messenger to communicate between two programs or machines.

Some popular APIs are Google Analytics; social media APIs like Twitter, YouTube, and Instagram; Weather API; MongoDB Data API.; and FlightStats API.

What apps use an API?

Many apps like Uber, Ola, and Instagram, apps provisioning universal logins, and retail sites having online payment options use APIs for the benefit of end users.

Why do we need an API?

An API acts as a messenger that can exchange information between two systems, without the need for additional infrastructure or human intervention. For example, using APIs, a flight booking website can communicate with multiple airline databases to get the best flight deals as per a user’s preferences. As a developer, an API lets you reuse functionalities that have been created by someone else, without having to re-code or copy them into your machine or environment.