Features

Videos

Articles

Events

Examples

Discord Webhooks

Github Webhooks

Slack Webhooks

Resources

© Pipedream, Inc. 2023

What is an API?

If you’re familiar with some development and basic software functionalities, then you probably would have come across the term “API” come up. Every now and then, we hear Operating systems, web browsers, and app updates announce new APIs for developers. But what is an API and what are they used for?

What Is an API?

API is an acronym that stands for Application Programming Interface. API can be defined as a set of definitions and protocols useful for building and integrating application software. API is basically a software intermediary that enables communication between two applications. To make it even more basic, each time you send an instant message or use an app like Facebook, you’re using an API.

(Constructed in paint)

To better understand what an API is, let us use the analogy of a restaurant. In a restaurant, you’re served a menu, that details a list of all the dishes offered in that restaurant at the time, as well as a

description of the dishes which you can order. Then, when you place an order on the menu item you want, the kitchen prepares the dish and serves it to you. You do not need to know exactly how the restaurant prepares the food. Your primary concern is the finished product delivered to your table.

Similarly, APIs come with a list of operations that software developers can use, alongside a description of each of these operations, describing what they do. And just like in the analogy of the restaurant menu, the developer doesn’t need to know how a particular operation is performed by the API, just that the operation is available and supported. For instance, a programmer doesn’t need to know how the operating system generates the “Open” dialogue box, just that the option to present the dialogue box is available.

Though this example isn’t the most technically accurate, developers can, and must sometimes insert custom data into the API to get the desired results. Perhaps, fitting this criteria ion to the example of the restaurant would mean having a restaurant where you get the possibility of providing some custom ingredients for the kitchen to work within preparing your dish. Now, that example would be more accurate.

APIs are a great time-saving tool for developers, in that it provides some handy implementations that they can take advantage of. By using these preprogrammed implementations, the amount of code needed in development can be reduced, and it also helps to ensure consistency in similar apps developed on the same platform.

An Example of an API

When you use a mobile application that requires internet connectivity, the application sends data to a server, which receives the data, interprets it, performs the necessary actions as prescribed by the user through the appl, and relays it back to your mobile phone. The data is then interested by the application is presented to you in a user-friendly way. Now, all these actions occur through an API.

Let us, again, review the example of the restaurant from earlier, where you’re served a menu that shows a list of available dishes in that restaurant. On the one hand, there’s the customer (that’s you), sitting at the reception table; and on the other hand, there is the processing system (the kitchen) that prepares the dish you ordered. What remains is a connecting link between the consumer and the system – that communications link that conveys the order to the system, and delivers the food to the consumer. In the restaurant, that link is called the waiter. In software development, that link is called API. The waiter (API) receives your order (request) and informs the kitchen (system) on what to do. Once the kitchen (system) is done with the order (request), it transmits the food (output) through the waiter (API) to the client.

Now, let’s review another real-life example of APIs – searching flights online using an online travel service like Expedia or Kayat. To book a flight online, you start by reviewing a list of options including different cities, departure and arrival dates and more. The way it works is, the online travel service interacts with the airline’s service and pulls the necessary information from their database and displays it to you, the client. From this information, you can choose the type of booking to make and which airline to use. This feedback is relayed back to the airline service and your reservation is made. Now, in this example, the API is the intermediary interface, like the waiter, that enables communications between the online travel service and the airline. The API conveys the airline’s response to the online travel service, which then presents the information to you.

A brief history of APIs

APIs have been around for a while, and were in use well before the personal computer was ever created. At the time, an API served as a library for operating systems, and was almost always local on the systems on which it operated, even though its functions sometimes extended to relaying messages between mainframes.  In short, APIs have been around since the advent of computing, and they became an essential technology for the remote integration of data from the start of this millennium.

How do APIs work?

APIs enable your products to services to communicate with other products and services, without requiring you to understand how the communications are implemented. This degree of abstraction makes app development easier, time and resource-efficient too.  APIs offer flexibility and simplicity while providing opportunities for innovations in your systems.

APIs have sometimes been viewed as contracts, with documentation that reflects an agreement between two parties, such that if party A sends a remote request structured in a certain way, there is a particular way party 2’s software will respond.

API also helps business and IT teams in an organization to better integrate as it simplifies how developers integrate new application components into existing architectures. This is especially useful because business needs often change quickly s they respond to ever-shifting digital markets, where a new competing app can change the entire industry. As such, to stay competitive, there must be constant updates, development and redeployment of new and improved innovative services. One clear way to increase development speed is by integrating cloud-native application development, which relies on connecting a microservices application architecture through APIs.

APIs also provide a simple way for your infrastructure to be connected through cloud-native app development, and they make it possible for you to share data with customers and other external users.

Here’s a simplified chart of how APIs work. Basically, the backend systems connected to the API, which, in turn, connects to the API management system, which finally connects to Apps and IoT devices

To better understand how APIs work, let us take the example of a book distribution company, where the book distributor gives out books to its customers using a cloud app. In this example, suppose the book distributor issues the cloud app to its bookstore clerks to check book availability with the distributor. In this case, the development of this app would be highly expensive, be limited by the platform and would require a long development time and very seasonal maintenance.

An alternative to such an app would be an API that checks stock availability. The benefits of going this route would be numerous:

• Giving customers access to such data via an API would help them better collect information about their inventory from one single interface.
• Integrating an API would give the distributer greater flexibility to make alterations to its internal systems without any concerns it would affect the customers, just so long as the APIs behavior doesn’t change.

• Depending on the API release policy, it is possible for developers working for the book distributor, booksellers or even other third parties to develop a search application that helps customers find books they’re looking for with greater ease. This would open up the company to more opportunities and even greater sales.

Essentially, APIs give you room to open up access to your resources while maintaining strict control and security. In fact, APIs let you determine how you open up the access and to whom, and you could use an API gateway to manage security. To connect APIs, or create applications that make use of API features, you can use a distributed integration platform that connects everything from legacy systems to the Internet of Things (IoT).

API Release Policies

Private: In the private API policy, the API is strictly for internal use. This policy allows the company the most control over its API.

Partner: In the partner policy, the API is shared with some specified business partners. This policy is great if you desire some additional revenue with very minimal compromise in quality.

Public: In the public API policy, the API is made available to everyone. This can be a source of innovation as it allows third parties to develop apps that would interact with your API. Public APIs greatly simplify and expand how you connect with your partners, as well as how you can potentially monetize your data. A popular example is the Google Maps API.

While private API may allow for the strictest control over your data, there are some unique privileges for exposing your APIs to partners or the public:

• It creates new revenue streams or expands existing ones.
• It expands the reach of your brand.
• It promotes open innovation and efficiency improvement through external development and collaboration.

Undoubtedly, these are amazing benefits of enabling the transition to partner and public APIs. But the, how do APIs’ do all this? To answer this, let us revisit the analogy of the book distribution company.

With the partner API policy, a partner of the company could develop an application that enables customers to search books on the bookshelf easily. This would automatically open up the company to more shoppers, and even distributors of the books would see a boom in revenue.

With a public API policy, a third party could also develop an application that would permit customers to purchase books directly from the distributor, rather than from the store. This would mean increased revenue streams for the distributor, and that all adds up to the progress of the company.

From this example, we see that exposing APIs to partners and the entire public can have tremendous positive impacts on the company. Basically, for every exposure of the API, it implies more exposure to your brand, and that translates to greater marketing opportunities and increase profits. With public and partner APIs others can build ecosystems of applications around your API, and as more persons use the apps, they’ll be more likely to do business with you or engage your brand.

Characteristics of the modern API

In the past, the term API was generally applied to any interface that permitted connectivity to an application. But in recent years, the modern API has evolved with some key characteristics:

• Modern APIs are compatible with more user-friendly standards that are easily accessible and have a broad applicability today, like HTTP and REST.
• Modern APIs are considered less as code and more as products, since they are designed to be consumed by a specific audience, like mobile developers, and so are most adapted to meet the expectations of that small niche of consumers.
• Modern API are more standardized, and so would be more secure and provide greater control over its use. They would, thus, be able to be monitored and managed for maximum performance.
• Also, since modern APIs are more standardized, they have their software development lifecycle (SDLC), comprised of the design, testing, building, managing, and versioning phases. They also have elaborate documentation for consumers.

Uses of APIs

APIs Enable Communication Between Services

The primary application of APIs is to enable communication between services. If you’ve ever seen a Google maps object, for example, embed on a website, then that website is using the Google Maps API to do. If such APIs didn’t exist, then programmers would have to write specialized code that generates such a map and input their data to serve their needs.

APIs Make App Development Easier

Suppose you want to design an app for an iPhone that would require that you embed a web browser in the app to display some web pages. Traditionally, you would have to code a web browser specifically for your app, but with the tons of APIs provided by the Apple iOS operating system, you could use the WKWebView API, for example, to embed a WebKit (Safari) browser object in your app and skip the hassle of writing new code. Now, that’s a great cut in the amount of time that would have been spent in developing such an application.

Again, suppose you want to create an application that would have to capture photos or videos from the phone’s camera and perfume some operations on it. Traditionally, you would have to write your own camera interface to interpret the camera’s input to achieve this. But with the camera API, you can simply embed the phone’s built-in camera in your application. The heavy-lifting has already been done by the phone OS developers and provided APIs as the extension cord to simply plug in and carry on your work.

And this benefit doesn’t just apply to mobile phones. Even on windows, you could use APIs to create dialogue boxes and windows, without having to program the dialogue box from scratch. Essentially, APIs exist so that developers don’t have to reinvent the wheel each time they need to use them.

APIs Control Access to Resources

APIs also function as administrators, controlling access to hardware and software resources that an application may or may not have permission to access. As such, APIs serve to ensure security.

As an example, you may have come across websites that pop a message in your browser requesting your precise location. In essence, that website wants to use the geolocation API in your browser. Your web browser exposes the possibility of access to your location, making it easier for developers to develop apps that rely on your location. When the request for your location comes, your web browser does the heavy lifting by accessing your GPS to find your exact location. This is where the security feature of APIs come it. Such requests can only be authenticated by the user. Perhaps you may have come across the term permissions on your phone and web browser. As the user, you grant permission to the website seeking your location and your web browser provides the information through an API. The only way websites can get access to physical resources like your GPS sensor is through an API and the web browser controls access to these hardware devices and which apps can use them. And this isn’t limited to web browsers.

The same principle applies to your mobile operating systems like Android and iOS, where apps must be granted permission by the user through the API to be able to access certain hardware resources. If an app requires access to your microphone, they go through the microphone API you can either approve or deny the permission request. If you deny the request, then the app has no way of accessing your phone's microphone. Even apps that require access to file systems do not have direct access to the raw physical storage device. They go through the file system API to manage your files.

APIs Provide a Layer of Security

As mentioned earlier, APIs serve to provide a layer of security. By using APIs, your data is never really exposed to the server as your application communicates with it, and likewise, the server is never really exposed to intrusion from your phone. Instead, APIs ensure that just the essential data is shared, without exposing either party to intrusion.

As a result of the security features of APIs, they have grown to comprise a significant part of the revenue of many large companies, like Google, Amazon, eBay, etc. that is how the term “API economy” came to be – the marketplace of APIs.

What is Remote APIs?

Remote APIs are a special category of APIs designed to operate through a communications network. The term remote implies the API is controlling resources that are located physically outside of the computer making the request. And since the internet is the largest and most widely used network of the time, it makes sense that most APIs are based on web standards. It is important to note that not all remote APIs are web APIs, but all web APIs are remote APIs as they operate across a communications network.

SOAP vs. REST

In discussing web APIs, we cannot avoid discussing SOAP. SOAP (Simple Object Access Protocol) is a special protocol specification developed to help standardize information exchange via APIs. SOAP protocol implemented on APIs receive requests through HTTP or SMTP and use XML as their standard message format. This makes it easier for apps to share information, even when they are written in different languages or are executed in different environments.

Another key concept in web APIs is REST. REST (Representational State Transfer (REST) is a type of API architecture, and Web APIs based on the REST architecture are called RESTful APIs. REST is primarily different from SOAP in that REST is an architecture, while SOAP is a protocol.

REST architectural constraints have six guiding characteristics:

1. Client-server architecture: The REST architecture is comprised of clients, servers, and resources, with request handling through HTTP.
2. Statelessness: For no reason should client data be stored on the server in between requests. Rather, all information about the session state is held with the client
3. Cacheability: the implementation of a cache lessens the need and dependence on some client-server interactions.
4. Layered system: Layers could be introduced to mediate client-server interaction, and offer some additional functionalities like security, load balancing, or shared caches.
5. Code on demand (optional): Servers can transfer executable code in a bid to extend the functionality of a client.
6. Uniform interface: This is a very important constraint to the design of RESTful APIs and comprises 4 aspects:
7. Resource identification in requests: Resources in requests are identified and are separate from the representations returned to the client.
8. Resource manipulation through representations: Clients receive files that represent resources, with enough information to allow modification or deletion.
9. Self-descriptive messages: With each message returned to a client, there is enough information to describe how the client should process the information.
10. Hypermedia as the engine of application state: The rest-client should be able to discover all other available actions after accessing a resource, with the use of hyperlinks.

Though these constraints may seem grievous at first glance, they are relatively simpler than a prescribed protocol, and this explains why RESTful APIs are more common than SOAP.

In summary, APIs serve as standard contracts that establish how developers communicate with a service, and the output the developers should expect in return.