Understanding OpenAPI Gateways

What is an OpenAPI Gateway?

An OpenAPI Gateway is an API gateway designed to natively support and process OpenAPI specifications. It directly interprets OpenAPI documents, removing the need for external tools or additional steps in pipelines.

Gateway Configuration with OpenAPI

Before OpenAPI, configuring each route in a gateway required manual effort. Specifying methods, paths, and policies for different endpoints was tedious and error-prone. OpenAPI descriptions simplify this process significantly, as they already contain necessary information such as HTTP methods, parameters, and content formats. Additionally, an OpenAPI document can include backend addresses for multiple environments, such as testing, quality assurance, or production.

An OpenAPI Gateway utilizes the comprehensive information provided in the OpenAPI document to configure APIs automatically. It reads the OpenAPI definitions and sets up the API to listen for incoming requests and route them appropriately to backend services. Furthermore, detailed parameter descriptions for query strings, paths, and payloads allow the API Gateway to provide enhanced request and response validation.

The following example demonstrates an API configuration that listens on port 80 and is fully configured via OpenAPI:

<api port="80">
  <openapi location="https://api.predic8.de/api-docs/fruit-shop-api-v2-2-0"
           validateRequests="yes"/>
</api>

To modify an API (e.g., adding endpoints or fields), no changes to the gateway configuration are needed. Simply update and reload the OpenAPI document.

Request and Response Validation

OpenAPI documents extensively describe requests and responses, enabling thorough validation of parameters such as:

• HTTP Method: POST or PUT?
• Path: Path including variables like /products/{id}
• Query Parameters: Query string parameters like ?sort=asc
• Content-Type: Format like JSON or XML
• Payload: Fields, datatypes and values of JSON documents

OpenAPI documents (YAML or JSON) also detail data types, formats, and constraints clearly. For example, consider the following product object that might be part of an OpenAPI description:

Product:
  type: object
  properties:
    id:
      type: integer
    name:
      type: string
      maxLength: 30
    price:
      type: number
      minimum: 0

Here, the price field must be a number greater than or equal to zero. If a request violates this constraint:

PUT /shop/v2/products/8 HTTP/1.1
Content-Type: application/json

{
  "name": "Mangos",
  "price": -2.79
}

The validator checks the request details against the OpenAPI specification. In this case, the validation fails because the price field does not meet the minimum value requirement. Consequently, the gateway returns a descriptive error message:

{
  "title": "OpenAPI message validation failed",
  "type": "https://membrane-api.io/problems/user/validation",
  "validation": {
    "method": "PUT",
    "uriTemplate": "/products/{id}",
    "path": "/shop/v2/products/8",
    "errors": {
      "REQUEST/BODY#/price": [
        {
          "message": "-2.79 is smaller than the minimum of 0",
          "complexType": "Product",
          "schemaType": "number"
        }
      ]
    }
  }
}

Validation ensures not only the presence of essential fields but also correct formatting and valid value ranges (e.g., ensuring ZIP codes have exactly five digits or numeric fields are within specified limits).

Why is Validation Important?

Data Quality

Validation ensures that data entering an API conforms to expected structures. It checks for required fields, data types, and value ranges, significantly improving data reliability and quality.

API Security

Input and output validation is a fundamental pillar of API security. IT security experts often advise, "Never trust input." OpenAPI validation allows rigorous checking of API inputs against detailed schema definitions. Invalid methods, paths, or potentially harmful payload content (such as injection attempts with special characters) can be immediately detected and blocked.

OpenAPI Support in Membrane API Gateway

Membrane is a native OpenAPI gateway supporting configuration directly from OpenAPI YAML and JSON files or URLs. It offers configurable validation capabilities for both requests and responses.

See: OpenAPI Configuration and Validation