What is APIs?

What is APIs?

Application Programming Interfaces (APIs) are module: they take inputs and give you predictable outputs. 

• At its core, an API is a bunch of code that takes an input and gives you an output

• Sometimes, companies will make parts of their APIs publicly available, like github, Twitter or Google Maps

• In modern era, your favourite applications are collection of APIs.

In WWW, the programmatic service is provided by the APIs. User/Automation access this service using the API. Whatever the way the service is implemented, it is abstracted from user. So, automation can use this API for their broader usage.

Generally, there are two types of APIs. Internal and Public. Internal APIs are used by companies for communicating with their internal applications. They are not open to public. Whereas, companies open ups their dataset with APIs. Interested users can do interesting things with it. A good example is twitter API, which lets people like you interact with tweet data programmatically.

API implementations: SOAP, REST, GRPC

There are three major protocols/technologies that developers use to build APIs: SOAP, REST and GRPC.

1. SOAP:

SOAP (Simple Object Access Protocol) is the oldest of the API protocols. It was originally released in 1998 by a few Microsoft engineers. It’s based on XML. Here’s an example of what kind of code you’d need to write to work with it:

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:m="http://www.example.org">
  <soap:Header>
  </soap:Header>
  <soap:Body>
    <m:GetStockPrice>
      <m:StockName>T</m:StockName>
    </m:GetStockPrice>
  </soap:Body>
</soap:Envelope>

This is legacy technology now. Companies are moving to new technology now.

2. REST

REST API stands for Representational State Transfer and is an architectural pattern for creating web services. It was developed by Roy Fielding in 2000 and has led to a growing collection of RESTful web services that follow the REST principles.

REST is a ruleset that defines best practices for sharing data between clients and the server. It’s essentially a design style used when creating HTTP or other APIs that asks you to use CRUD(create/read/update/delete) functions only, regardless of the complexity.

REST applications use HTTP methods like GET, POST, DELETE, and PUT. REST emphasizes the scalability of components and the simplicity of interfaces. Not all HTTP APIs are REST APIs. The API needs to meet the following architectural requirements to be considered a REST API:

1. A uniform interface: An API must expose specific application resources to API consumers.
2. Client-server independence: The client and the server function independently. The client will only know the URIs that point to the application’s resources. These are usually published in the API documentation.
3. Stateless: The server doesn’t save any data pertaining to the client request. The client saves this “state data” on its end (via a cache). Learn more about stateful vs. stateless systems here.
4. Cacheable: Application resources exposed by the API need to be cacheable.
5. Layered: The architecture is layered, which allows different components to be maintained on different servers.
6. Code-on-Demand (COD): This is the only optional REST constraint. This allows the client to receive executable code as a response from the server. In other words, it’s the server that determines how specific things get done.

3. gRPC

gRPC (Remote Procedure Call) is made mostly for distributed systems that optimize for scale and low latency. gRPC is an open-source RPC architecture designed by Google to achieve high-speed communication between microservices. gRPC allows developers to integrate services programmed in different languages. gRPC uses the Protobuf (protocol buffers) messaging format, which is a highly-packed, highly-efficient messaging format for serializing structured data. For a specific set of use-cases, a gRPC API can serve as a more efficient alternative to a REST API.

BASICS OF AN REST API REQUEST:

A. The endpoint

The endpoint (or route) is the url you request for. It follows this structure:

root-endpoint/?

The root-endpoint is the starting point of the API you’re requesting from. The root-endpoint of Github’s API is https://api.github.com while the root-endpoint Twitter’s API is https://api.twitter.com.

B. The method

The method is the type of request you send to the server. You can choose from these five types below:

C. The Headers

Headers are used to provide information to both the client and server. It can be used for many purposes, such as authentication and providing information about the body content. HTTP Headers are property-value pairs that are separated by a colon. The example below shows a header that tells the server to expect JSON content.

{
    Content-Type: text/html; charset=UTF-8,
    Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
}

D. The Body

The data (sometimes called “body” or “message”) contains information you want to be sent to the server. This option is only used with POST, PUT, PATCH or DELETE requests.

{
    user_id: 34,
    order_date: "2020-01-01",
    order_value: "99.99"
}

Request bodies are generally formatted as JSON (this format of name:value).

Where and how to call APIs

a. Browsers

The endpoint to get a list of my repos on Github is this: https://api.github.com/users/prmanna/repos

If you’d like to get a list the repositories that I pushed to recently, you can set sort to push. https://api.github.com/users/prmanna/repos?sort=pushed

b. Command Line

cURL is a popular command line tool for making API requests: you just choose your method and endpoint, and then attach any extra data like headers or a request body.

c. Client Libraries

Internal and vendor APIs often ship with built in functions for specific programming languages. If your company uses mostly Python for the backend, they might create a library to interact with their APIs and build functions like listOrders() that you can use directly.

d. IDEs

Like with the rest of the programming ecosystem, there are specialized tools for querying REST endpoints. The most popular one out there is Postman. it organizes your request into simple form fields, helps autocomplete your headers and body, and lets you store credentials and settings.

There are few more alternative for API implementations, like, GraphQL, Thrift, via queuing like RabbitMQ,

In the next article, I’ll cover the device management/automation using Netconf, restconf.