API (Application Programming Interface)
Introduction
An API, Application Programming Interface, is protocol that enables two or more software components to communicate with each other.
APIs are used to simplify application development by exposing abstract interfaces and hiding their actual implementation. This takes away application integration complexity and allows dynamic connectivity between software components.
APIs have been in existence since the early days of computers and are used to describe the interface of applications (a term used for an end-user facing computer program). Eventually the term became broader and included other programs too, like utility software, server-to-server communication, and hardware interfaces too. This document is focused on the software aspect communication with hardware or hardware-hardware communication are not a part of this article.
As APIs evolved and increased in stature, new protocols were developed to describe and use the APIs.
Defining of API
An API is a contract between applications. Following are the key aspects of an API’s definition:
1. Functionality
Each functionality must be clearly defined. It must define expected responses based on arguments, expected errors and error scenarios. There must not be ambiguity in any functional definitions, if any are found at a later stage, the objective should be their prompt resolution. Accessibility
Accessibility of an API functionality must be well defined. It can be changed over time as a platform evolves and new features are added or made obsolete. Accessibility should be defined for each API separately.
2. Security
The security of an API functionality must be defined for a group of APIs based on its accessibility and its functionality. An API might be secured via one or multiple ways ranging from API Key, user credentials, Mutual TLS, OAuth 2.0, OpenID Connect, and/or Security Certificate. Security of an API must be defined based on application, API Sensitivity, and certification requirements.
3. Data Exchange Format
An API functionality should have a well-defined data exchange format. It might be binary, plain text, XML, or JSON. It can define object type based on selection of an API protocol.
4. Protocol
The API protocol defines the way services interact with each other. There might be multiple protocols across the platform integration. In that case, an API must define the protocols it will support. API Types
API types by accessibility
1. Public/Open API
Public/Open APIs are open to the public, and available for everyone to use. There might be some or all Public API endpoints that need user access tokens, but they do become private. These measures might be for security and maintainability purposes.
API Life Cycle: These APIs rarely change since they are used widely and hence have longer life and a slower upgrade process. These should have backward compatibility measures, especially with newer versions.
2. Partner API:
Partner API endpoints are accessible to partners only. The partners might be internal (within the organization), or external partners, such as customers, or strategic development partners. There might be distinct levels of access to APIs based on the partner level. There are different requirements for responses based on partner level and these APIs have different implementations for the same API endpoint.
API Life Cycle: These APIs have faster version upgrades as their usage is limited usage. These APIs must be backward compatible, but they might become obsolete faster than the public or open APIs.
3. Private/Internal API:
Such APIs are usually used with specific groups of applications in teams. They are exposed to only specific groups within the organization.
API Life Cycle: These APIs change fast and usually they do not support backward compatibility. Even if they need to provide backward compatibility, it is for just a few releases.
Customarily, any public or partner APIs are considered private for initial releases post development and during alpha releases for internal testing, or released to some partners too for internal development and they should not be exposed to public. These are frequently changing APIs.
API types by aggregation
1. Composite API
A composite API clubs multiple API calls and exposes it as a single API call. It reduces the number of API calls that makes the application more efficient and improves the performance and it may reduce the overall cost for operation. These are used to optimize performance, reduce overall costs, and improve user experience.
API Life Cycle: Such APIs have longer life.
2. Unified API
Unified APIs perform multiple operations by calling multiple API wrapped in a single call. They may raise security issues if not properly implemented. However, they can be designed and implemented to improve security. Unified APIs can be used to support atomicity and consistency that might not be possible via multiple calls from the client. There are other common cases where Unified APIs are developed to call multiple Private or Protected APIs to keep it secured.
API Implementation Architectures
The following are key API architectures used widely in Cloud Application development.
1. Monolithic Architecture
Monolithic architecture implementation contains all the APIs developed as a single comprehensive code for APIs. In this architectural implementation, each functionality is coupled together that makes it easy to implement but it is overly complex in terms of feature management and deployment.
Benefits:
a. Simple usage: All features and functionalities are part of a single application; hence it uses the same best practices for development and can use development technology such as caching, logging, and monitoring libraries.
b. Easy for development: Being a single application, it is developed in a single set of related technologies. Since all the functionalities are implemented as a single code base, single architecture definition is followed for every functionality, and it makes application easier to test, debug and optimize performance.
c. High Application Performance: As the entire application shares the memory and code, in certain cases, it improves functionality drastically.
Drawbacks:
a.Complexity: The first and major drawback of monolithic architecture is complexity. Considering that everything is implemented as a single application, it leads to difficulty in functional separation and isolation. It is extremely hard to understand all the features of an application.
b. Scalability: Given that monolithic applications are usually big and process every functionality as a single application, they need higher computing capabilities. Where there may be a single functional spike for a few hours in a day, a new full-fledged server is needed to be deployed for use during peak usage for a single functionality.
c. Technology selection: As the application is with a single unit, it is hard to use different programming languages for specific features. It makes it extremely hard to introduce modern technology for specific functionalities.
d. Release: As all functionalities are placed as a single application, any feature enhancements need a completely new release that needs to be tested for everything. This adds to the difficulty with every feature enhancement.
2. µ-service / Microservice architecture
In µ-service architecture, functional components are implemented independently as µ-services are based on functional requirements. These pluggable lightweight µ-services are implemented for specific functionality and expose a predefined set of APIs that allow other µ-services to communicate with them.
Benefits:
a. Service independence: µ-services are categorized as functional services, and they are independent services connected with each other via a common gateway. This makes it easier to enhance features and release them with ease.
b. Scalability: Considering that these services are lightweight and use fewer resources, more instances can be deployed when required.
c. Technology selection: Based on functional requirements, it is easier to use different technologies for specific services.
Drawbacks:
a. Development: As every feature is developed as an independent service, it takes more time to develop against monolithic architecture. Often the developers are used to monolithic development and may need some time to adjust to a new architecture style.
Key API Protocols
The API protocol defines how components (or software components, or applications or software systems) would connect and communicate with each other. The protocol impacts the design and implementation of applications. This impact may either ease the design and development of application, or it may increase complexity of application and future implementation. API protocols should be defined by their scope of application. It is advisable to use multiple protocols based on the application/platform requirements.
Web API
Web APIs are used to transfer data over networks using HTTPs. These APIs are categorized based on their usage and accessibility. Web APIs might be secured based on application requirement.
Following are key accessibility areas for Web APIs: REST APIs (Representation State Transfer)
REST APIs work over HTTP method and HTTP protocol. They were developed as part of web standards in 2000. REST APIs are widely used due to following reasons:
- Simplicity: They are developed to work over HTTP and make use of HTTP methods, hence quite easy to understand and implement.
- Scalability: APIs are transferrable between client and server. They can be scaled easily and can be made available across geological locations.
- Data Format Compatibility: REST APIs can work with any data format like JSON, XML or even on plain text. They make use of HTTP headers to accept data format and based on the headers, they generate response data.
- Cache Support: As APIs are standard, they can easily cache the frequently used API endpoints to generate faster responses. Clients can use cache via HTTP headers.
SOAP API (Simple Object Access Protocol)
SOAP is one of the simplest forms of APIs. SOAP transmits XML data over different mediums. These are not limited to HTTP/HTTPS, but data can also be transferred using SMTP, TCP, and UDP. SOAP APIs are simple, and their usage is broad. They are easy to deploy and implement but hard to debug.
SOAP message contains:
Envelope: The envelope defines the message structure and contains processing information.
Header information: This is optional for SOAP message. Its usage is application specific and contains authentication information, contextual information, language information, and/or payment information. This information is used to process the SOAP message on application,
Body: The body contains the actual message that needs to be processed. It has a defined namespace to understand the details of the body.
Remote API
Remote APIs are developed to execute remote resources through standard protocols. Remote APIs are platform/language specific implementations, and these are distinctive features of languages. For Object Oriented Languages, they allow developers to create proxy objects of remote type. They can use them to execute remote methods via special implementation. Ex. Java Remote method invocation
RPC API (Remote Procedure Call)
RPC Protocol returns XML, JSON, or Protocol Buffer (Protobuf) as data carrier for various calls. These APIs do work on the remote method call rather than on the data like REST and SOAP. These APIs are commonly defined for distributed applications. This provides a way for a front-end application to make server method calls without any special mechanism between the client and server. It simplifies and decouples a distributed client-server implementation.
API Definition Goals
An API definition should provide following benefits to business:
1. Speed
An API should provide easier task completion to API clients that will help the business enhance functionality by adding new features.
2. Scalability
As the platform grows, it will have more data and requests from clients. APIs should have capabilities to handle this growth.
3. Security
It should be easier to secure every functionality or group of functionalities based on application platform requirements/
4. Collaboration
API functionalities should have defined appropriate accessibility, security, and protocol support that will make multiple client integration possible.
5. Enhanced User Experience
API functionalities should provide complete sets of functionalities with optimized options for input parameters for other client services. They should also enable user-facing applications to improve user-experience without performance, and security degradation.
6. Reduced Cost
Building and deploying an application, irrespective of its size, is a significant investment. APIs should be easy to implement with cost effective technology solutions and optimized resource utilization.
7. Faster Development
API design and functionalities should support easy implementation of the client applications and support distinct options that enable the clients accomplish multiple tasks.
8. Improved Enhancements
APIs functionalities should be implemented in a way that will allow enhancement of API without worry about breaking existing functionality. The enhancements should be easier over time.
