What is API Schema?

An API schema defines the structure, types, and constraints of the data exchanged between a client and a server. It specifies the endpoints, request parameters, response structure, and other details that allow developers to understand how to interact with the API effectively by providing a clear blueprint, and API schema to ensure consistency, reliability, and easier maintenance of the API. Basically APIs enable communication between different software systems and they allow various applications to interact with each other for sharing data and functionalities. APIs define the method and data formats that applications use to communicate acting as an intermediary that translates requests and responses.

These are the following topics that we are going to discuss:

Why is it Needed?

• APIs are essential for building and integrating software systems and they
• Enable different systems to work together.
• Allow third-party developers to extend functionalities.
• Facilitate the creation of microservices architectures.
• Enable the development of mobile and web applications.
• Improve the efficiency of data exchange and functionality integration.

Types of API Schemas

• OpenAPI
• RESTful API Modeling Language
• API Blueprint

OpenAPI

The OpenAPI Specification is a standard for defining RESTful APIs. It allows both humans and computers to discover and understand the capabilities of a service without access to source code or documentation.

Syntax:

OpenAPI definitions can written in JSON or YAML format.

openapi: 3.0.0
info:
  title: Sample API
  description: A sample API to illustrate OpenAPI specification
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Where:

• Info Section
  • openapi: The version of the OpenAPI specification.
  • info: Contains metadata about the API, including the title, description, and version.
• Servers Section
  • servers: Defines the base URL for the API.
• Paths Section
  • paths: Defines the endpoints available in the API.
  • /users:
    • get: Specifies the GET method for retrieving a list of users.
    • summary: A brief description of the operation.
    • operationId: A unique identifier for the operation.
    • responses: Defines the possible responses.
      • 200: Indicates a successful response, with the content type and schema specified.
  • /users/{id}:
    • get: Specifies the GET method for retrieving a single user by ID.
    • summary: A brief description of the operation.
    • operationId: A unique identifier for the operation.
    • parameters: Defines the path parameter id.
    • responses: Defines the possible responses.
      • 200: Indicates a successful response, with the content type and schema specified.
      • 404: Indicates that the user was not found.
• Components Section
  • components: Contains reusable components such as schemas.
    • schemas:
    • User: Defines the structure of the User object.
      • type: Specifies the type of the schema (object).
      • properties: Lists the properties of the User object.
        • id: An integer representing the user's ID.
        • name: A string representing the user's name.

Example:

Here we provide an example YAML format code snippet for reference purpose. In this YAML file we configure open api version, title description and version information. And It contains paths with content type, description, HTTP success code and other information.

openapi: 3.0.0
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0
paths:
  /users:
    get:
      summary: Returns a list of users.
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

RAML

The full form of the RAML is RESTful API Modeling Language. The RAML is language designed for defining RESTful APIs emphasizing simplicity and readability. It aims to make it easy to design, build and consume APIs.

Syntax:

RAML definitions are written in YAML.

#%RAML 1.0
title: Sample API
version: v1
baseUri: https://api.example.com/v1
mediaType: application/json

/users:
  get:
    description: Retrieve a list of users
    responses:
      200:
        body:
          application/json:
            type: User[]
types:
  User:
    type: object
    properties:
      id: integer
      name: string

Where:

• Title and Version: The title and version of the API are specified at the top.
• Base URI: The base URI where the API is hosted.
• /users Endpoint: Defines a GET request to retrieve a list of users. The response is specified to return a JSON array of user objects.
• /users/{id} Endpoint: Defines a GET request to retrieve a user by ID. The uriParameters section specifies that id is an integer and required. The response returns a user object in JSON format.

Example:

Here we provide a YAML code snippet for reference. And this code snippet contains information like RAML version, title, version, baseUri, mediatype and user API paths. This code snippet can be used to generate API documentation and client code.

#%RAML 1.0
title: Sample API
version: v1
baseUri: http://api.sample.com/{version}
mediaType: application/json

/users:
  get:
    description: Returns a list of users.
    responses:
      200:
        body:
          application/json:
            type: array
            items: User

types:
  User:
    properties:
      id: string
      name: string

API Blueprint

API Blueprint is a documentation oriented API description language. It focus on creating comprehensive API documentation and mock servers

Syntax:

API Blueprint definitions are written in Markdown.

FORMAT: 1A
HOST: https://api.example.com/v1

# Sample API

## Users Collection [/users]

### List All Users [GET]

+ Response 200 (application/json)
    + Attributes (array[User])

# Data Structures

## User (object)
+ id: 1 (number)
+ name: John Doe (string)

Where:

• FORMAT and HOST: Specifies the format version and the host where the API is hosted.
• Group Users: Groups endpoints related to users.
• Retrieve a list of users: Defines a GET request to the /users endpoint. The response is specified to return a JSON array of User objects.
• Retrieve a single user by ID: Defines a GET request to the /users/{id} endpoint. The Parameters section specifies that id is a required number. The response returns a User object in JSON format.
• Data Structures: Defines the User object structure with id and name properties.

Example:

Below we provide a basic code snippet for API Blueprint. And a well documented API specification that can be used to generate interactive documentation and mock servers. This code snippet contains information like application content type, HTTP Status code, HOST information and other information.

FORMAT: 1A
HOST: http://api.sample.com

# Sample API

## Users [/users]

### List Users [GET]
+ Response 200 (application/json)

    + Body

            [
                {
                    "id": "1",
                    "name": "John Doe"
                }
            ]

Benefits of API Schema

• Modularity and Reusability: APIs allow developers to create reusable and modular software components.
• Interoperability: APIs enable different systems and platforms to work together.
• Flexibility and Scalability: APIs support the development of scalable and flexible applications.
• Security: APIs can help enforce security protocols by controlling access to data and functionalities.
• Efficiency: APIs streamline the process of integrating different systems saving time and resources.

Conclusion

Each approach to defining an API schema provides a structured, clear way to describe the API's capabilities. Depending on the requirements, such as the need for flexibility, efficiency, or documentation, developers can choose the most suitable approach. OpenAPI is ideal for RESTful APIs needing comprehensive documentation and tooling support. GraphQL is perfect for APIs that require flexible, efficient data querying. RAML is great for easy-to-read, concise API definitions. API Blueprint focuses on creating rich, interactive API documentation. gRPC is optimal for high-performance, cross-language APIs.