Are you an API Architect? Apply these standards for defining Event-driven and RESTful APIs

Post Views: 9,232

With the rise of Cloud, Microservices, and Cloud-native technologies, API development is one of the key focus areas for organizations – both from an internal and external integration perspective.

Figure A – Services & API Standards Evolution

OpenAPI – Standard for RESTful APIs

OpenAPI specification (originally based on Swagger 2.0) has become the de facto industry standard for HTTP APIs providing the programming-language agnostic interface. Key highlights are:

OpenAPI can not only describe APIs based on the HTTP protocol (RESTful) but also APIs based on HTTP-like protocols like CoAP (Constrained Application Protocol) or WebSockets. It supports both YAML & JSON format.
Promotes design-first API development, maintains single source of truth across (code & specification are synchronized), supports documentation as part of code, supports multiple IDEs, etc.
Key advantages are automation opportunities because of machine-readable format such as API description validation & linting, data validation, document generation, code generation, mocking APIs, security analysis, etc.
Supported by most of the API Platforms or API Management tools such as MuleSoft, ApiGee, RapidAPI, WSO2.
Adopted by product companies from different industry sectors such as financial services – PLAID, Bloomberg or technology companies such as Ambadassor Labs (Cloud-native Kubernetes), Liferay (Digital Experience Platform).
Key links:

Async API – Standard for asynchronous event-driven APIs

Async API has started becoming the industry standard for defining asynchronous APIs. For event-driven and microservices architecture, asynchronous communication is the need of the hour and a common standard helps to build the semantics common understanding. Key highlights are:

An open source initiative targeted to improve the current state of Event-Driven Architectures (EDA).
Supports both JSON & YAML as message format and AsyncAPI document is a machine-readable for event-driven API. OpenAPI goal is to work collaboratively with other standards like OpenAPI, GraphQL, and gRPC definitions.
AsyncAPI is not a competitive specification to OpenAPI rather it is a collaborative specification. It emerged as an adaptation of the OpenAPI specification (see comparison below).
Click here to see the list of tools supporting as Code Generators, Documentation, Mocking & Testing, Validators, etc.

Source: https://www.asyncapi.com/docs/getting-started/coming-from-openapi

Cloud Events – Specification for describing event data

CloudEvents (part of CNCF now) is relatively new to create a specification for describing event data in common formats to provide interoperability across services, platforms, and systems. Key highlights are:

Emerging standard to support event-driven architecture focused primarily on events to decouple provider and consumer supporting interoperability between systems.
In comparison to Async API, Cloudevents focuses on message format than API itself and gets applied to FaaS (function-as-a-service) or any system exchanging event or message with a common industry format.
Async API and CloudEvents are not competing specifications can be used together.
Apart from event attributes and related metadata, it also focuses on how to serialize the event in different formats (e.g. JSON) and protocols (e.g. HTTP, AMQP, Kafka).
Supported by cloud event bus, and event-oriented solutions (including Serverless) such as Argo Events (Event-driven Workflow Automation Framework), OpenFaaS (Serverless framework to deploy event-driven functions and microservices to Kubernetes), Serverless Workflow (specification that defines a vendor-neutral and declarative workflow language), Google Cloud Eventarc (to build event-driven architectures with loosely coupled services that react to state changes), Azure Event Grid, Oracle Cloud Events, Alibaba Eventbridge, etc.

Examples

OpenAPI Example

openapi: 3.0.0
info:
  description: OpenAPI Specification for the a Hello World API
  version: 1.0.0
  title: Hello World API
paths:
  /:
    get:
      summary: Provides hello world message
      operationId: Sends hello world message
      description: Provides a simple Hello World message using GET operation
      parameters:
        - name: user
          in: query
          description: Your name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
servers:
  - url: http://api.vedcraft.com

Async API Example

asyncapi: 2.1.0
info:
  title: Hello world message
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string
          pattern: '^hello .+$'

CloudEvents Message Example

{
    "specversion" : "1.0",
    "id" : "V123-456-789",
    "source" : "https://api.vedcraft.com/helloworld",
    "type" : "com.vedcraft.helloworld",
    "subject" : "message",
    "time" : "2021-08-30T09:05:00Z",
    "datacontenttype" : "application/json",
    "data" : "{\"fname\": \"ankur\", \"lname\":\"kumar\"}"

}

References:

Ankur Kumar