Location on Create

Category: HTTP Headers

Description

Resource creation operations (POST and PUT) should include a Location header in successful responses, pointing to the URI of the newly created resource.

What It Checks

This rule validates that POST and PUT operations identified as creating resources include a Location header in their 2xx (successful) responses. The rule uses LLM analysis to determine if an operation is a creation action by examining:

• The endpoint path
• The HTTP method (POST or PUT)
• The operation's summary
• The operation's description

Once identified as a creation operation, the rule checks all 2xx responses for the presence of a Location header.

Why It Matters

Including a Location header for resource creation is a fundamental REST principle:

• Discoverability: Clients can immediately navigate to the newly created resource without constructing the URI themselves
• Decoupling: The server controls URI structure; clients don't need to know the URI pattern
• HTTP Compliance: Follows RFC 7231 specification for creation responses
• Best Practice: Aligns with industry standards and developer expectations

Examples

Good ✅

paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: User created successfully
          headers:
            Location:
              description: URI of the created user
              schema:
                type: string
                example: /users/12345
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /organizations/{orgId}/projects:
    post:
      summary: Create a project
      responses:
        '201':
          description: Project created
          headers:
            Location:
              description: URI of the created project
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'

  /items/{itemId}:
    put:
      summary: Create or replace item
      responses:
        '201':
          description: Item created
          headers:
            Location:
              description: URI of the item
              schema:
                type: string
                example: /items/abc-123

Bad ❌

paths:
  /users:
    post:
      summary: Create a new user
      responses:
        '201':
          description: User created successfully
          # Missing Location header!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /organizations:
    post:
      summary: Register a new organization
      responses:
        '200':
          description: Organization created
          # Missing Location header!
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string

  /resources/{id}:
    put:
      summary: Create resource with specific ID
      responses:
        '201':
          description: Resource created
          # Missing Location header!

Configuration

This rule has no configuration options. It is either enabled or disabled.

The rule automatically identifies creation operations using LLM analysis, so it adapts to various API design patterns and naming conventions.

How to Fix

1. Add Location header to POST creation responses:

   responses:
     '201':
       description: Resource created
       headers:
         Location:
           description: URI of the created resource
           schema:
             type: string
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Resource'
   

2. Add Location header to PUT creation responses (when PUT is used for creation):

   responses:
     '201':
       description: Resource created
       headers:
         Location:
           description: URI of the resource
           schema:
             type: string
             example: /resources/{id}
   

3. Use absolute or relative URIs:

   # Relative URI (recommended)
   Location: /users/12345
   
   # Absolute URI (also valid)
   Location: https://api.example.com/users/12345
   

4. Include Location for all success responses (200, 201, 202, etc.):

   • If you return multiple 2xx codes, include Location in all of them
   • Most commonly used with 201 (Created)
   • Sometimes used with 202 (Accepted) for async operations

Related Rules

• Rule 27: Use 201 for Creation - Status code for created resources
• Rule 45: Response Headers - General header usage patterns
• Rule 67: HATEOAS Links - Hypermedia navigation (complements Location header)