API stands for Application Programming Interface, which is a mechanism that allows the interaction between two applications using a set of rules. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.
There are four main types of APIs as rapidapi states in their blog:
Open APIs: Also known as Public API, there are no restrictions to access these types of APIs because they are publicly available.
Partner APIs: A developer needs specific rights or licenses in order to access this type of API because they are not available to the public.
Internal APIs: Also known as Private APIs, only internal systems expose this type of API. These are usually designed for internal use within a company. The company uses this type of API among the different internal teams to be able to improve its products and services.
Composite APIs: This type of API combines different data and service APIs. It is a sequence of tasks that run synchronously as a result of the execution, and not at the request of a task. Its main uses are to speed up the process of execution and improve the performance of the listeners in the web interfaces.
APIs can also be categorized, depending on who are they communicating with, as northbound or southbound, and also depending on how the API caller handle their transactions, as synchronous or asynchronous.
Northbound APIs
Northbound APIs are interfaces that allow a component to communicate with higher level components, making available to these higher level components a layer of abstraction of the lower level details. Usually, in computer networking the most common example would be a controller’s interface to communicate with a management software or third party applications (e.g. Ansible, OpenStack, etc.).
The most common of these APIs and the ones within our scope would be the web services APIs, exposing a resource through the network via HTTP.
A web service it’s a software function provided at a network address over the Web with the service always-on, listening for requests at a particular port over a network and providing web applications services, they could use different protocols, architectures, frameworks, or in short, ways of interacting with the APIs, some of the most common are:
RPC: Remote Procedure Call causes a procedure (subroutine) to execute in a different address space (commonly on another computer on a shared network), without the programmer explicitly coding the details for the remote interaction. RPC endpoints can implement business logic inside the service making it great for "actions", it's essentially the same as calling a function in JavaScript, PHP, Python and so on, taking a method name and arguments, you don't see or access resources directly.
XML-RPC: Is a remote procedure call (RPC) protocol which uses XML to encode its calls and HTTP as a transport mechanism. It's older than SOAP, uses minimum bandwidth and is much simpler.
JSON-RPC: This protocol is similar to XML-RPC but instead of using XML format to transfer data it uses JSON.
SOAP: Simple Object Access Protocol, defines an RPC mechanism using XML for client-server interaction across a network by using HTTP as the base transport and XML documents for encoding of invocation requests and response. SOAP is both low-entry and high-function, capable of use for simple stateless remote procedure calls as well as rich object systems. For more information you can refer to the IETF internet-draft
REST: Representational State Transfer is an architectural style consisting of a set of constraints, first coined by Roy Fielding in his year-2000 thesis.
The main constraints that characterize REST would be, among others not mentioned:
Client-Server architectural style.
Communication must be stateless in nature.
Responses could be cacheable.
Uniform interface between components
REST-based APIs are great for modeling your domain (that is, resources or entities), making CRUD (create, read, update, delete) available for all of your data. In a RESTful Web service, requests made to a resource's URI will receive a response with a payload formatted in many formats, most common formats for our case would be XML and JSON.
Southbound APIs
Southbound APIs, as you would expect, contrary to Northbound APIs, are the ones facing to the managed elements, in networking these would be the switches, routers and many other infrastructure devices. Controllers would push changes using these APIs.
Protocols used by these APIs could be NetConf, RestConf, gNMI and many other network management protocols, but those are the ones we are focusing for now in future blog posts.
Synchronous APIs
When a client or application is using a synchronous API, the client is blocked until a response is returned from the server, or a user-defined optional timeout occurs, before continue its normal operations.
This could happen when the application depends on this information to continue working, sometimes leading to delays for the application.
Asynchronous APIs
Asynchronous would be the opposite, which allows the application to send multiple requests in parallel without the need to wait for the reply.
The sender of an asynchronous message is only blocked for the time taken for the system to process the message locally. The remote system does not guarantee that the message has been deposited at the destination location.
Weebhooks
A webhook is an HTTP callback, or an HTTP POST, to a specified URL that notifies an app when a particular activity or event has occurred in one of the resources you subscribe to in the subject or target app. As you might notice, this follows the Observer Design Pattern previously explained.
A good example of these are Cisco Webex demos, using webhooks to create chat bots that reply certain user messages, this is possible by leveraging these Webex webhooks which notifies the bot app.
There are a variety of standalone cloud webhook services like Built.io, hook.io, Zapier, etc., which are able to receive and/or forward webhooks, or you could send these notifications to your own apps for them to trigger some actions on these.
API Authentication
Just to be clear, authentication is the act of proving an assertion, such as the identity, in summary, proving who you are. On the other hand, authorization would specify access rights/privileges to resources, which is related to access control in particular. Here we will discuss APIs authentication methods.
In APIs the authentication is done by the exchange of credentials or claims that the server can use to confirm such identity.
The type of identities used by the APIs would be specific to each use case, but they are usually, user identities, app identities or integrations and sometimes even bot identities.
The most common types of authentications used for APIs to assert those identities are:
Cookies
Cookies are a small piece of data that a server sends to the user’s web browser. The browser may store it and send it back with later requests to the same server.
This type of authentication uses HTTP cookies to authenticate client requests and maintain session information.
Cookie authentication is vulnerable to Cross-Site Request Forgeries (CSRF) attacks, so it should be used together with other security measures
Basic Auth
Basic Auth is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with an Authorization header that contains a base64-encoded string username:password.
Because base64 is just an encoding scheme, these credentials could be easily decoded, Basic authentication should only be used together with other security mechanisms such as HTTPS/SSL.
API Keys
API Keys are tokens that a client provides when making API calls. The key can be sent in the query string, a request header or as a cookie.
API keys are supposed to be a secret that only the client and server know. Like Basic authentication, API key-based authentication is only considered secure if used together with other security mechanisms such as HTTPS/SSL.
Token or Bearer Auth
Token Auth is an HTTP authentication scheme that involves security tokens. The name can be understood as “give access to the bearer of this token”. The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources.
The Bearer authentication scheme was originally created as part of OAuth 2.0 in RFC 6750, but is sometimes also used on its own. Similarly to Basic authentication, Bearer authentication should only be used over HTTPS (SSL).
OAuth
OAuth is an authorization protocol that gives an API client limited access to user data on a web server. The most recent version is OAuth 2.0.
Here are some key concepts that might be useful to better understand OAuth in depth:
OAuth client is the entity that accesses protected resources. (e.g. App)
Resource owner is the entity that owns protected resources. (e.g. user)
Authorization server is the server that is either the authorization endpoint or the token endpoint.
Resource server is the server that stores protected resources that the OAuth client accesses.
Access token is an identifier to access the protected resources of the resource owner. The OAuth client can use the access token before it expires and the resource server honors the access token.
OAuth relies on authentication scenarios called flows or grants, which allow the resource owner to share the protected content from the resource server without sharing their credentials. The most common OAuth grant types are listed below:
Authorization Code grant type is the most common or the one that we are more exposed to as users, it allows confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.
Client Credentials are used by clients to obtain an access token outside of the context of a user. This is typically used by clients to access resources about themselves rather than to access a user's resources.
Device Code is used by browserless or input-constrained devices in the device flow to exchange a previously obtained device code for an access token.
Refresh Token is a grant used to obtain access tokens when the initial token has expired or to request an access token with identical or narrower scope, refresh tokens are not sent to the resource server. The authorization server generates the refresh token together with the access token.
Some legacy grants are:
Implicit Flow was a simplified OAuth flow previously recommended for native apps and JavaScript apps where the access token was returned immediately without an extra authorization code exchange step. As you can imagine, due to the inherent risks it is not recommended to use this flow anymore.
Password Grant was a way to exchange a user's credentials for an access token. Because the client application has to collect the user's password and send it to the authorization server, it is not recommended that this grant be used at all anymore.
As IBM explains in its knowledge center, some of these grants can have different workflows Two-legged OAuth flow or Three-legged OAuth flow.
Two-legged (Requires a grant type of Password or Client Credentials):
Two-legged OAuth processing flow.
The OAuth client can be either the resource owner or the trusted entity that knows about the credentials of the resource owner. In other words, two-legged OAuth processing does not involve additional resource owner interaction.
An OAuth client initiates a request with an authorization server and receives an access token.
The OAuth client uses the access token to access protected resources on the resource server.
A user, as the resource owner, initiates a request to the OAuth client.
The OAuth client sends the resource owner a redirection to the authorization server.
The resource owner authenticates and optionally authorizes with the authorization server.
The authorization server presents a form to the resource owner to grant access.
The resource owner submits the form to allow or to deny access.
Based on the response from the resource owner, the following processing occurs:
If the resource owner allows access, the authorization server sends the OAuth client a redirection with the authorization grant code or the access token.
If the resource owner denies access, the request is redirected to the OAuth client but no grant is provided.
The OAuth client sends the authorization grant code to the token endpoint (authorization server)
If verified, the authorization server sends the OAuth client an access token and optionally a refresh token.
The OAuth client sends the access token to the resource server to request protected resources.
If the access token is valid for the requested resources, the OAuth client can access the protected resources.
OpenAPI defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIS.
