# 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.

[![Services & API Standards Evolution](https://vedcraft.com/images/2021/08/API-Standards.png)](https://vedcraft.com/images/2021/08/API-Standards.png)

Figure A – Services & API Standards Evolution

[![OpenAPI - Standard for Request/Response based HTTP APIs](https://vedcraft.com/images/2021/08/OpenAPI_Logo_Pantone-1-1024x309.png)](https://www.openapis.org/)

## OpenAPI – Standard for RESTful APIs

[OpenAPI specification](https://spec.openapis.org/oas/latest.html) (originally based on [Swagger 2.0](https://swagger.io/)) 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)](https://coap.technology/) or [WebSockets](https://datatracker.ietf.org/doc/html/rfc6455). 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](https://www.mulesoft.com/), [ApiGee](https://cloud.google.com/apigee), [RapidAPI](https://rapidapi.com/), [WSO2](https://wso2.com/api-manager/).
-   Adopted by product companies from different industry sectors such as financial services – [PLAID](https://www.openapis.org/blog/2021/04/13/leveraging-the-openapi-specification-in-financial-services-the-story-of-plaids-openapi-journey), [Bloomberg](https://www.techatbloomberg.com/) or technology companies such as [Ambadassor Labs](https://www.getambassador.io/) (Cloud-native Kubernetes), [Liferay](https://www.liferay.com/) (Digital Experience Platform).
-   Key links:
    -   [Github repository with specification, style guide, documentation, etc.](https://github.com/oai)
    -   [Best practices by OpenAPI](https://oai.github.io/Documentation/best-practices.html), [Best practices collated as part of community – Stylebook](http://apistylebook.com/design/guidelines/)
    -   [Swagger Inspector – API documentation and testing online tool](https://swagger.io/tools/swagger-inspector/)
    -   [Swagger UI – visualize and interact with APIs](https://swagger.io/tools/swagger-ui/), [Swagger Editor for designing APIs](<http://Design, describe, and document your API on the first open source editor fully dedicated to OpenAPI-based API>)

* * *

![Async API - Standard for Asynchronous Event-driven APIs](https://vedcraft.com/images/2021/08/async-api.png)

## Async API – Standard for asynchronous event-driven APIs

[Async API](https://www.asyncapi.com/) 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](https://www.asyncapi.com/docs/community/tooling) to see the list of tools supporting as Code Generators, Documentation, Mocking & Testing, Validators, etc.

![](https://vedcraft.com/images/2021/08/Compare-OpenAPIAsyncAPI-556x1024.png)

Source: [https://www.asyncapi.com/docs/getting-started/coming-from-openapi](https://www.asyncapi.com/docs/getting-started/coming-from-openapi)

* * *

![Cloud Events Logo](https://vedcraft.com/images/2021/08/cloudevents.png)

## Cloud Events – Specification for describing event data

[CloudEvents](https://cloudevents.io/) (part of [CNCF](https://www.cncf.io/) 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](https://github.com/argoproj/argo-events) (Event-driven Workflow Automation Framework), [OpenFaaS](https://docs.openfaas.com/) (Serverless framework to deploy event-driven functions and microservices to Kubernetes), [Serverless Workflow](https://serverlessworkflow.io/) (specification that defines a vendor-neutral and declarative workflow language), [Google Cloud Eventarc](https://cloud.google.com/eventarc/docs/) (to build event-driven architectures with loosely coupled services that react to state changes), [Azure Event Grid](https://azure.microsoft.com/en-us/services/event-grid/), [Oracle Cloud Events](https://blogs.oracle.com/cloud-infrastructure/post/track-and-react-to-cloud-native-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](https://swagger.io/resources/articles/difference-between-api-documentation-specification/)
-   [Roadmap for AsyncAPI Specification](https://www.asyncapi.com/roadmap)
-   [Detailed Comparision of AsyncAPI and CloudEvents](https://www.asyncapi.com/blog/asyncapi-cloud-events)