What is an API?

APIs are the primary method of software integration. They set the rules and protocols that define how applications communicate with each other in situations where they need to work together.

APIs enable a modular approach to software integration, improving system flexibility by:

• Enabling the extensibility of core services by letting developers integrate them with complementary services, leading to more powerful system capabilities

• Decoupling services by tucking backend processes behind the API’s abstraction layer, which allows developers to independently maintain, scale, replace, or remove services

Let’s take a closer look at APIs and how to use them:

How do APIs work?

APIs function as a common language between independent services. For services to work together, they need a shared communication method. APIs are an integration language both can understand and use.

• API calls are requests from one service to another
• API responses are what the service returns

Types of APIs

There are several types of APIs. Here are a few common ones:

• REST is a web-based API with flexible use cases
• SOAP is an XML-based API used in legacy systems
• OData is a query API for filtering, sorting, and paginating

API design

REST, SOAP, and OData each have their own structures and formats. Let’s take a look at the REST API, which is the most common API architecture and has the simplest design.

Here’s what it looks like:

• The call contains a method, endpoint, headers, and body
• The response contains headers, a status, and body

These components also have standard formats:

• The HTTP method or requested action follows the format:
  • GET to read
  • POST to create
  • PATCH to update
  • PUT to replace
  • DELETE to remove

• The URL endpoint is a web-based access point with path hierarchy

• The headers, which contain metadata, such as:
  • “Authorization” to authenticate the client
  • “Content-Type” to define the data format
  • “Accept” to define the response format

• The body contains any data that services need to share using the format defined in the headers, typically JSON. It’s optional. For example, a “POST” request to create a new contact might include new contact details, while a “DELETE” request to remove a contact wouldn’t include any data.

• The status is an error handling feature where HTTP status codes indicate success or failure

API examples

Let’s say one service asks another about the weather in London.

The REST API call will look something like this (method, endpoint, and headers):

GET /weather?city=London&units=metric
Host: api.openweathermap.org
Authorization: Basic 8dbf5d2a37c4178b4b03f6ae3f9e7

And the response will look something like this (headers and body):

{
“temperature”: 18,
“description”: “few clouds”,
“humidity”: 65
}

For more API examples, check out this blog post by Keshav Malik, Security Engineer at Workato.

API security

There are two common ways to secure APIs: API keys and OAuth 2.0.

An API key is a unique string of characters included in the query, as a cookie, or in the “Authorization” header. It is an authorization method that verifies that the request is coming from a known client.

API providers can also use the API key to track usage, enforce rate limits, and flag suspicious spikes.

Each service has a unique key. The REST API call above includes the key for the OpenWeatherMap API:

8dbf5d2a37c4178b4b03f6ae3f9e7

API keys provide a basic level of security, but have several shortcomings: they track clients not users, they can be exposed, and attackers can reuse the key from a legitimate call to launch replay attacks.

Most developers use the OAuth 2.0 standard instead of API keys. This authorization method uses temporary access tokens that allow secure access to APIs without exposing user credentials. It lets developers authorize and track users, not just clients, and give them fine-tuned access and permissions.

How to use APIs

The use cases for APIs are extensive. They range from simple point solutions, like sending notifications with a webhook, to complex product development applications, where you might use APIs to:

• Drive innovation by building upon existing services
• Add value to your products by connecting them to others

Let’s say you simply want to integrate two third-party services. Here’s how to use APIs:

1. Define the use cases for the integration
2. Identify the data to be exchanged
3. Map out the process for that use case
4. Find the endpoint and key for each service
5. Automate the process with API calls
6. Test it and make any modifications

You can do all of this in Workato using either pre-configured API integrations (called “connectors”) or building your own with the HTTP Connector. Workato’s orchestration layer also has advanced features, like load balancing and error handling, so that you can build more complex integration ecosystems.

The key capabilities of Workato’s API platform are:

• The API gateway, which offers robust capabilities for managing your APIs, integrating advanced security, efficient routing, and effective mediation to ensure optimal performance and reliability

• API governance, which ensures that your APIs are secure, compliant, and managed according to the best practices of activity auditing, versioning, lifecycle management, and access control

• API design, which accelerates API development with intuitive features that simplify the creation, deployment, and management of your APIs

• API monitoring, which tracks and analyzes API usage and performance with comprehensive monitoring and analytics tools such as the API platform dashboard

• API security, which supports OAuth 2.0 and other authentication methods to ensure secure access to APIs

For more details, see Workato’s documentation.