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

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.

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:
  • Github repository with specification, style guide, documentation, etc.
  • Best practices by OpenAPI, Best practices collated as part of community – Stylebook
  • Swagger Inspector – API documentation and testing online tool
  • Swagger UI – visualize and interact with APIs, Swagger Editor for designing APIs

---

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.

---

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:

• Differences Between API Documentation, Specifications, and Definitions
• Roadmap for AsyncAPI Specification
• Detailed Comparision of AsyncAPI and CloudEvents