What is OpenAPI?

OpenAPI: What Is It?

OpenAPI is a specification language for HTTP APIs. It defines a structure and syntax independent of any programming language. The API specification is written in YAML or JSON. All of this allows the implementation and consumption of the API to be in any programming language and be independent of each other.

A very important aspect is that it serves as a communication language between developers, teams and organizations, because it provides a clear definition of your API. Because it’s a standard for API specifications, there are a lot of tools and IDEs supporting it.

API Lifecycle

OpenAPI specification can support you in every phase of your API lifecycle, if you approach an API first style.

An explanation of some the stages above:

• Requirements: Business and product teams come together to define the requirements. Having a first idea of the API in any form enables you to enter the design phase.
• Design: Converts the abstract idea of the API in a well-defined specification, which is also versionable.
• Configure: An API management tool could be used to create API gateway configuration based on the specification. Automatic configurations could be created to verify the request of the consumer, e.g. validate the path and parameters, request body etc.
• Develop: Code can be generated based on the specification.
• Test: Allows developers to take the role of API consumers. Tools can be used to perform contract tests to check that design and implementation do match. Because it’s clearly defined what the API is supposed to provide, security tests could be performed to reveal if anything is exposed unintentionally or if security holes are present.

What You Can Automate

Having your API in a machine-readable format opens up a lots of capabilities. Some of which are:

• Description Validation and Linting: Check that your description file is syntactically correct and adheres to a specific version of the Specification.

• Data Validation: Check that data entering and leaving your API is correct in development and production.

• Documentation Generation: Create up-to-date and human-readable documentation on the fly.

• Code Generation: Create both server and client code in any programming language, freeing developers from having to perform data validation or write SDK glue code, for example.

• Mock Servers: Create fake servers providing example responses which you and your customers can start testing with before you write a single line of code.

• Security Analysis: Discover possible vulnerabilities at the API design stage instead of much, much later.

Structure Of OpenAPI Specification

The specification is written as one or more text documents in either JSON or YAML format.

References are used to link parts of the JSON object(s) to each other, and this linked structure is the complete OpenAPI Description. The document begins with an OpenAPI root object, and the document containing that object is known as the entry document, commonly called openapi.json or openapi.yaml. Please visit the OpenAPI documentation for details.

Below the structure of the root object is visualized:

A exemplary OpenAPI specification written in YAML:

openapi: 3.0.0
info:
  title: Simple API
  description: A basic API with a single endpoint
  version: '1.0.0'
servers:
  - url: https://api.example.com/v1
    description: Production server
paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      description: Returns a single user by their ID
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user to retrieve
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  username:
                    type: string
                  email:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
                required:
                  - id
                  - username
                  - email
        '404':
          description: User not found
        '500':
          description: Internal server error

The specification consists of some metadata and a single HTTP end point /users/{userId} accepting a required parameter named userId of type integer. It returns an object with 4 attributes in case of success, whereby the attribute createdAt is optional. It defines also error cases, where an appropriate HTTP status code alongside with a corresponding description is returned.

You can generate code based on that specification, share it with other teams or organizations and put it in a version control system like Git.

References

• OpenAPI
• OpenAPI Spec Explained
• OpenAPI Tooling
• Visualization Of OpenAPI Structure