AEP-0151 Linter Rules

Rules for AEP-151: Long-running operations

The aep-151 rules check that long-running operations follow the proper patterns for returning 202 Accepted responses with Operation resources, and ensure that services with long-running operations provide the required operations endpoints.

Overview

Overview

Long-running operations are operations that take a significant amount of time to complete. Instead of blocking the client, these operations should return a 202 Accepted response with an Operation resource that can be used to track progress and retrieve the result.

aep-151-200-only-success

aep-151-200-only-success

Rule: Long-running operations must return 202 as the only success status code

This rule ensures that operations returning 202 Accepted do not also define a 200, 201, or 204 response, as mandated in AEP-151.

Details

This rule looks for operations that have a 202 response and complains if they also have a 200, 201, or 204 response defined. Long-running operations must be consistent in their behavior - they should either always return 202 with an Operation, or never do so.

Examples

Incorrect code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '200':
          description: Book created immediately
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Book'
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'

Correct code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '500':
          description: Internal server error

Disabling

If you need to violate this rule for a specific operation, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/paths/books/post/responses'
    rules:
      aep-151-no-200-success: 'off'

aep-151-202-schema-required

aep-151-202-schema-required

Rule: 202 response must define an application/json response body with Operation schema

This rule ensures that 202 Accepted responses include a content definition with an application/json response body, as mandated in AEP-151.

Details

This rule looks for 202 responses and complains if they do not have a content field with an application/json media type defined that contains a response body schema.

Examples

Incorrect code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '202':
          description: Book creation accepted
          # Missing content field

Correct code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'

Disabling

If you need to violate this rule for a specific operation, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/paths/books/post/responses/202'
    rules:
      aep-151-202-content-required: 'off'

aep-151-operation-schema

aep-151-operation-schema

Rule: Operation schema properties must have correct types

This rule ensures that the Operation schema properties have the correct data types, as mandated in AEP-151.

Details

This rule validates that:

• The path property has type string
• The done property has type boolean
• The error and response properties are objects

Examples

Incorrect code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                type: object
                properties:
                  path:
                    type: boolean # Should be string
                  done:
                    type: string # Should be boolean
                  error:
                    type: object
                  response:
                    type: object

Correct code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                type: object
                properties:
                  path:
                    type: string
                  done:
                    type: boolean
                  error:
                    type: object
                  response:
                    type: object

Disabling

If you need to violate this rule for a specific operation, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/paths/books/post/responses/202/content/application/json/schema/properties'
    rules:
      aep-151-operation-properties: 'off'

aep-151-operations-endpoint

aep-151-operations-endpoint

Rule: Services with long-running operations must define an operations endpoint with list and get operations

This rule ensures that services with long-running operations provide the required operations endpoints for querying operation status, as mandated in AEP-151.

Details

This rule checks that if any operation returns a 202 response, the service must define:

• /v1/operations endpoint with a get operation (for listing operations)
• /v1/operations/{operation} endpoint with a get operation (for getting a specific operation)

Examples

Incorrect code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'
  # Missing operations endpoints

Correct code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      responses:
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'
  '/v1/operations':
    get:
      summary: List operations
      responses:
        '200':
          description: List of operations
          content:
            'application/json':
              schema:
                type: object
                properties:
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
  '/v1/operations/{operation}':
    get:
      summary: Get operation
      parameters:
        - name: operation
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operation details
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'

Disabling

If you need to violate this rule for a specific service, add an “override” to the Spectral rule file for the specific file.

overrides:
  - files:
      - 'openapi.json'
    rules:
      aep-151-operations-endpoint: 'off'

Complete Example

Complete Example

Here’s a complete example of a long-running operation that follows all AEP-151 rules:

openapi: 3.0.3
info:
  title: Book Service API
  version: v1
paths:
  '/books':
    post:
      summary: Create a book
      operationId: CreateBook
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/CreateBookRequest'
      responses:
        '202':
          description: Book creation accepted
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'
        '400':
          description: Bad request
        '500':
          description: Internal server error
  '/v1/operations':
    get:
      summary: List operations
      operationId: ListOperations
      responses:
        '200':
          description: List of operations
          content:
            'application/json':
              schema:
                type: object
                properties:
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
  '/v1/operations/{operation}':
    get:
      summary: Get operation
      operationId: GetOperation
      parameters:
        - name: operation
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operation details
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Operation'
components:
  schemas:
    Operation:
      type: object
      properties:
        path:
          type: string
          description: The path to the operation
        done:
          type: boolean
          description: Whether the operation is complete
        error:
          type: object
          description: Error information if the operation failed
        response:
          type: object
          description: The result of the operation when done
        metadata:
          type: object
          description: Service-specific metadata
          additionalProperties: true
    CreateBookRequest:
      type: object
      properties:
        title:
          type: string
        author:
          type: string
      required:
        - title
        - author