Application Programming Interface (API)

An application programming interface (API) is a way for two or more computer programs to communicate with each other.

API specification language

  • OpenAPI

OpenAPI

OpenAPI, an evolution of Swagger, is a specification for describing APIs in a standardized way.

The OpenAPI Specification (OAS) establishes an interface for describing an API in a way that allows any developer or application to discover it and fully understand its parameters and capabilities.

Architectural types

API architectural types:

  • SOAP
  • RESTful
  • Query-based
  • Model-context protocol

SOAP

SOAP is known because of its structured way.

RESTful API

Representational State Transfer (REST) is an architectural style that originally described how distributed hypermedia systems (like the web) should behave when interacting. More specifically and in some given context, it can also considered that it describes how a client and server should interact.

It was defined Roy Fielding in 2000.

REST main principles:

  • Client-Server Architecture: Separation of concerns between the user interface and data storage.
  • Statelessness: Each request from the client must contain all necessary information; the server does not store session state.
  • Uniform Interface: Using a standardized way to identify and interact with resources (such as URIs).
  • Cacheability: Responses must define themselves as cacheable or not to improve efficiency.
  • Layered System: The client cannot tell if it is connected directly to the end server or an intermediary like a load balancer.
  • Code on Demand (Optional): The server can temporarily extend client functionality by returning executable code instead of data structures.

REST is applied to APIs, web services or databases (like CouchDB).

A RESTful API, is an application programming interface (API or web API) architecture that conforms to the constraints of REST and allows for interaction with RESTful services.

Though RESTful API are ubiquitously used on websites and HTTP, it is protocol-independent and can be used on other protocols like FTP, SMTP or custom protocols like socket-based.

REST calls web resources by using uniform resource identifiers (URIs).

RESTful are lighter than SOAP, but less robust against errors.

Other characteristics:

  • They assume stateless communication
  • They are mainly based on URIs to access data and achieve the uniform interface.
  • It allows clients to discover actions through links (HATEOAS
  • It is synchronous, real-time oriented.
  • Offers outputs in many formats, such as JSON (preferred data format) or XML
  • It is frequently used on HTTP protocol, using HTTP request methods, such as GET, POST, DELETE or PATCH and HTTP replies such as 200, 204, 404 or 409.

It was originally proposed by Roy Fielding by Microsoft.

OData (Open Data) is a REST-based protocol that defines how to build and consume RESTful APIs. It includes conventions for:

  • Querying data ($filter, $select, $expand)
  • Metadata exposure ($metadata)
  • Data modeling (via EDM, Entity Data Model)

OData could be described using OpenAP, so they complement each other.

Query-based API

A query-based API allows the client to request the structure of the data to be returned by the server.

An example of query-based API is GraphQL.

Model context protocol

Model context protocol (MCP) is used in AI.

Web API

A web API is an API that allows communication through the internet. Because of their popularity, web API are often referred simply as API.

An open API or public API is an API that can be accessed by anyone. This concept usually applies to web APIs.

Most web APIs use HTTP as the protocol to exchange messages.

A web API is considered by some authors as a broader term than web service, while others consider the opposite.

It can be contended that a web service may include a web API, and that a web service is a type of web API.

The fact is that the technologies that are traditionally related to the concept of web services (SOAP and WSDL) are older than those traditionally related to web API (RESTful and gRPC).

HTTP methods are used within the HTTP protocol to exchange information. Some of these methods are POST and GET.

Data query and manipulation language

API architectures:

  • GraphQL

GraphQL

GraphQL is a data query and manipulation language for APIs.

It is an alternative to RESTful API.

There are different GraphSQL servers:

  • Express GraphSQL
  • Mercurius
  • Apollo

Express GraphSQL is FOSS.

Mercurius is FOSS under a MIT license.

Apollo is a suite of tools for working with GraphQL, which includes the Apollo Server and Apollo Client libraries. Apollo Server is a server-side JavaScript library that helps you build GraphQL APIs, while Apollo Client is a client-side JavaScript library that allows you to consume those APIs from your front-end application.

Apollo is source-viewable software, under an Elastic license.

API Formats

Some formats used for API communication are JSON or XML, among others.

SOAP works only with XML format, while REST is compatible with different formats like JSON and XML.

API Platforms

An API platform is a tool designed for developing, testing, and consuming APIs. They help developers interact with APIs, send requests, inspect responses, and debug.

You can read this post about API platforms. It includes tools like Postman.

API Management

API management consists of providing full lifecycle management for APIs, including design, security, analytics, monetization, and governance.

These tools help organizations publish, control, and monitor APIs efficiently.

An API gateway is a component of an API manager.

You can read this post about API management.

API Models

API models, according to CCSP certification:

  • Public API
  • Partner API
  • Private or internal API

Declarative API

Declarativeness is a programming paradigm where the programmer indicates the desired state. It opposes other programming paradigms like imperative, where the programmer indicates the action to take.

A declarative API is an API that is centered around the desired state.

API Security

Common API security issues are:

  • Authorization for object access
  • Authentication weaknesses
  • Rate limiting

OWASP top 10 API on this external link.

OWASP API Security Project on this external link.

An API gateway is set before an API to aggregate API access, provide authentication for API use, rate-limit, and gather statistics and data about API usage.

An API gateway can be installed in the perimeter of a network. There are cloud API gateway like Amazon API Gateway.

API Document Generator

Doxigen can be used as API document generator.

Concepts related to API

A web service is a service offered over the web. You can read this post about web services.

Universal Description, Discovery, and Integration (UDDI) is an standard issued by OASIS that describes a protocol to register and publish web services.

Electronic Data Interchange

Electronic Data Interchange (EDI) is a standard to exchange business information between computer systems. It uses standardized formats like ANSI X12 or EDIFACT.

EDI Standards

EDI standards:

  • EPCIS
  • IDoc

EPCIS

An example of EDI is EPCIS, a GS1 standard that helps to share information about the physical movement

IDoc

IDoc is a proprietary EDI format, owned by SAP SE. It is used as the internal exchange format on SAP modules and systems (like SAP ECC and SAP CRM).

It is suited for batch-oriented, asynchronous communication.

IDoc was native to SAP ECC and it is still supported in SAP S/4HANA.

Remote procedure call

Remote procedure call (RPC) is…

RPC framework

RPC frameworks:

  • gRPC

gRPC

Google Remote Procedure Call (gRPC) is a RPC framework.

You might also be interested in…

External References

Leave a Reply

Your email address will not be published. Required fields are marked *