🎉 Exciting News! Introducing Our New NestJS Series: Unveiling the Power of OpenAPI 📚

We are thrilled to announce the launch of a brand-new series dedicated to unraveling the capabilities of OpenAPI within the NestJS framework. 🚀 Join us on this enlightening journey as we delve deep into the world of modern API documentation and design practices.

Topics Covered:

📋 Types and Parameters of OpenAPI: Learn about the essential components of the OpenAPI Specification. Learn how to specify data types, request/response formats, and other parameters properly to create APIs with remarkable clarity and precision.

🔀 Operations in OpenAPI: Explore operations in OpenAPI to get to the heart of API development. We'll walk you through the process of mapping HTTP methods, routes, and arguments to build smooth client-server interactions.

🔒 Security in OpenAPI: Discover the techniques for efficiently safeguarding your APIs. Investigate authentication and authorization mechanisms, as well as security schemes for protecting your endpoints and data.

📝 Mapped Types in OpenAPI: Mapped types will help you improve your API documentation. Learn how to design and apply schemas and data models to ensure consistency and improve the user experience of your API customers.

🎨 Decorators and Elevating API Documentation: Set out on an adventure to improve your API endpoints with decorators. Investigate how these powerful annotations may turn your NestJS APIs into well-documented, highly functioning resources.

Join us as we deep-dive into each topic, providing clear explanations, practical examples, and real-world use cases that will equip you with the skills to harness the full potential of OpenAPI within the NestJS ecosystem.

What is an OpenAPI?

The OpenAPI Specification (OAS), commonly known as Open API, is a standardized framework for describing and documenting APIs (Application Programming Interfaces). It allows developers to understand an API's capabilities and behavior without having to examine its source code.

Key elements in an API include endpoints, HTTP methods, request and response formats, parameters, data models, and authentication mechanisms. Endpoints describe API features, HTTP methods, data formats, parameters, and data models that define the data objects communicated between clients and APIs.

Advantages

• Developers can easily understand API functions and interact with them, improving cooperation.

• The Open API definition offers living documentation that can be updated automatically.

• APIs with the Open API standard provide a uniform experience, independent of source.

Use Cases: Open API helps API providers create user-friendly documentation, while API consumers use it for code production, testing, and interface learning. API gateways are configured for easy management, monitoring, and security.

What are the Types of OpenAPIs and their Parameters?

There are numerous key types and parameters in the context of the OpenAPI Specification (OAS) that play a critical role in characterizing and documenting APIs. These types and parameters serve to specify how an API operates and how it may be interacted with. Here are some of the most important kinds and parameters:

1. API Paths and Endpoints

   The API's many features are represented via endpoints. Paths, which are URLs that relate to certain resources or actions, are used to define them.

    paths:
      /users:
        get:
          summary: Get a list of users
   

2. HTTP Methods in APIs

HTTP methods describe the activities that can be performed on an endpoint. The most common methods are GET, POST, PUT, DELETE, and so on. They specify how the API reacts to certain sorts of requests

paths:
  /users:
    get:  # HTTP GET method
      summary: Get a list of users

1. Parameters

Parameters are used to send data to API endpoints. There are several sorts of parameters, such as:

• Path parameters: Variables in the URL's path section.

• Query parameters: Parameters added to the query string of a URL.

• Header parameters: These are parameters that are supplied in the request header.

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer

1. Request and Response Formats

These parameters specify the format of the data submitted in the request body and returned in the response. JSON and XML are two popular formats:

paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'

1. Authentication and Authorization

Authentication and authorization parameters aid in the security of the API. API keys, OAuth tokens, and JWTs are all common approaches.

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

1. Data Models and Schemas

The structure and data types of objects sent between the client and the API are defined by schemas. They may be used on many endpoints and responses

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string

How do operations APIs work in OpenAPI?

• An "operation" in the OpenAPI Specification (OAS) refers to a specific API endpoint or action that may be done on a resource.

• The HTTP method (GET, POST, PUT, DELETE, etc.), the endpoint path, and the arguments and request/response data associated with that action determine how clients can interact with the API.

• The HTTP method specifies the type of action performed on the endpoint, including GET, POST, PUT, DELETE, PATCH, and HEAD.

• The summary and description describe the operation's purpose and behavior. Parameters include path parameters, query parameters, header parameters, request body data, responses, request body and content, and security requirements.

• Responses define possible outcomes and data returned to the client, with HTTP status codes and descriptions.

• A request body and content can be defined for operations requiring a request body.

Example for operation definition in OpenAPI:

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      description: Retrieve user details based on the provided user ID.
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

The GET /users/{userId} operation retrieves user details using a user ID path parameter, with a JSON response following the schema in the components section. Operations are essential for OpenAPI definitions.

What's the Key to Ensuring Robust Security in OpenAPI?

OpenAPI supports various security schemes for API endpoints, including API Key, Bearer Token, Basic Authentication, OAuth 2.0, and OpenID Connect. These schemes define authentication and authorization methods for API endpoints. A security requirement object specifies the required security schemes for a specific operation, listing the names required for access.

1. Security Schemes: Security schemes specify how API endpoint authentication and permission are handled. OpenAPI is compatible with a variety of security mechanisms.

2. Security Requirement Object: A security requirement object specifies which security schemes are necessary for a certain action. It contains the names of the security schemes that must be met to gain access to the operation.

paths:
  /secure-resource:
    get:
      summary: Access secure resource
      security:
        - apiKey: []
        - bearerAuth: []
      responses:
        '200':
          description: Successful response

The security array in this example states that the apiKey or bearerAuth security scheme (or both) must be met to access the GET /secure-resource action.

Components: You can specify reusable security scheme objects in the components portion of your OpenAPI specification. This makes referencing security schemes throughout your API specification a breeze.

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

The security schemes section defines two security schemes (apiKey and bearerAuth). In the header of the apiKey scheme, an API key is used, whereas the bearerAuth scheme utilizes a bearer token (JWT).

Global Security Requirements:

You can establish global security criteria that apply to all API activities. This can help simplify the specification by eliminating redundancy.

security:
  - apiKey: []
  - bearerAuth: []

to be continued...

Stay tuned for the upcoming articles in the series, where we'll demystify OpenAPI's intricacies and empower you to create robust, well-documented APIs. Subscribe to our channel to ensure you don't miss any part of this enlightening journey!

Let's embrace the world of modern API design together! 🌐🔗