How to Add HTTP Headers Location in YAML file on Open API 3

In the world of API development, proper documentation is crucial for clarity and understanding.
One essential aspect is defining response headers, particularly for HTTP status code 201 Created, which indicates a successful resource creation.

In this brief guide, we'll explore how to add a Location header in the OpenAPI YAML file to enhance your API documentation.

Why Define Response Headers?

When designing RESTful APIs, it's important to specify the headers returned with each response. The Location header, in particular, informs the client where to locate the newly created resource. This is valuable information for developers integrating with your API.

Steps to Add Location Header in OpenAPI YAML

To add a Location header for a 201 Created response in your OpenAPI specification, follow these steps:

Define the Response in YAML

Locate the section where you describe the API operation within your YAML file. Typically, this is under the paths section for a specific endpoint.

paths:
  /your-endpoint:
    post:
      responses:
        '201':
          description: Object created successfully
          headers:
            Location:
              description: The location of the newly created object
              schema:
                type: string
                format: uri

Specify the 201 Response

Inside the responses section for your endpoint's POST operation, define the 201 response and include the Location header.

responses:
  '201':
    description: Object created successfully
    headers:
      Location:
        description: The location of the newly created object
        schema:
          type: string

Customize the Description

Provide a clear description for the Location header to explain its purpose and usage within your API documentation.

Implementing the Response

When a client sends a POST request to your API endpoint and the operation results in a 201 Created response, the server should include the Location header with the URL where the newly created resource can be accessed.

Practical Example

Upon a successful POST request:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/resource/123

The Location: /api/resource/123 header informs the client about the URL of the newly created resource.

Conclusion

Adding headers like Location in your Open API YAML file enhances the documentation of your API, making it more comprehensive and developer-friendly.

By following these steps, you ensure that consumers of your API understand how to interact with it effectively, improving overall usability and integration.