AEP-0133 Linter Rules

Rules for AEP-133- Standard Create method

# Rules for AEP-133: Standard Create method

aep-133-id-parameter

Rule: Create method should allow the user to specify the ID component of the resource.

This rule enforces that declarative-friendly create methods include a client-specified ID query parameter, as mandated in AEP-133.

Details

This rule looks at the parameters of “post” operations on a path that does not have a ”:” in its final segment (indicating a custom operation), and complains if there is no parameter with the name id.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    post:
      description: 'No parameters'
  '/test2':
    post:
      description: 'No id parameter'
      parameters:
        - name: force
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Ok

Correct code for this rule:

paths:
  '/book':
    post:
      parameters:
        - name: id
          in: query
          schema:
            type: string

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/test1/post'
    rules:
      aep-133-id-parameter: 'off'

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

aep-133-operation-id

Rule: The operation ID should be Create{resource-plural}

This rule enforces that all standard Create methods have an operationId field with a value that begins with “Create”.

Details

This rule looks for “post” operations on a path that does not end in a path parameter, and complains if the ‘operationId’ field is not present or if the value does not begin with “Create” (case insensitive) or a ”:” (for custom methods).

Examples

Incorrect code for this rule:

paths:
  # Missing operationId
  '/books':
    post:
      summary: Create a book
      responses:
  # operationId present but does not start with "Create"
  '/publishers':
    post:
      summary: Create a publisher
      operationId: MakePublisher

Correct code for this rule:

paths:
  '/books':
    post:
      summary: Create a book
      operationId: CreateBook

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#/books/post/operationId'
    rules:
      aep-133-operation-id: 'off'

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

aep-133-param-types

Rule: The id parameter must be a query parameter

This rule checks that the id parameter is a query parameter, as mandated in AEP-133.

Details

This rule looks at the parameters of “post” operations on a path that does not have a ”:” in its final segment (indicating a custom operation), and complains if the parameter with name of “id” is not a query parameter with type string.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    post:
      parameters:
        - name: id
          in: header
          schema:
            type: string

Correct code for this rule:

paths:
  '/test1':
    post:
      parameters:
        - name: id
          in: query
          schema:
            type: string

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/test1/post/parameters/0'
    rules:
      aep-133-param-types: 'off'

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

aep-133-request-body

Rule: A standard Create method must accept the resource in the request body

This rule checks that Create methods accepts the resource to be created in the body of the request, as mandated in AEP-133.

Details

This rule looks at “post” operations on a path that does not have a ”:” in its final segment (indicating a custom operation), and complains if there is no requestBody defined, or if the requestBody does not define a “content” with a schema that is an AEP resource.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    post:
      description: 'No request body'
  '/test2':
    post:
      description: 'Request body is not a resource'
      requestBody:
        content:
          application/json:
            schema:
              type: string
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/books':
    post:
      operationId: CreateBook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              'x-aep-resource':
                singular: book
                plural: books

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/test1/post/parameters/0'
    rules:
      aep-133-request-body: 'off'

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

aep-133-required-params

Rule: Create method must have no required parameters other than path parameters

This rule checks that Create methods have no required parameters other than path parameters, as mandated in AEP-133.

Details

This rule looks at the parameters of “post” operations on a path that does not have a ”:” in its final segment (indicating a custom operation), and complains if it finds any required parameters that are not path parameters (which must be required).

Examples

Incorrect code for this rule:

paths:
  '/test1':
    post:
      parameters:
        - name: force
          in: query
          required: true
          schema:
            type: boolean

Correct code for this rule:

paths:
  '/test1/{id}/test2':
    post:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: force
          in: query
          schema:
            type: boolean

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/test1/post/parameters/0'
    rules:
      aep-133-required-params: 'off'

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

aep-133-response-body

Rule: A standard Create method must return the resource in the response body

This rule checks that Create methods return the resource in the body of the response, as mandated in AEP-133.

Details

This rule looks at “post” operations on a path that does not have a ”:” in its final segment (indicating a custom operation), and complains if there is no responses defined, no 200 or 201 response, or if any response does not define a “content” with a schema that is an AEP resource.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    post:
      description: 'No request body'
  '/test2':
    post:
      description: 'Request body is not a resource'
      requestBody:
        content:
          application/json:
            schema:
              type: string
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/books':
    post:
      operationId: CreateBook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              'x-aep-resource':
                singular: book
                plural: books

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/test1/post/parameters/0'
    rules:
      aep-133-response-body: 'off'

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

aep-133-unknown-optional-params

Rule: Create methods should have no unknown optional parameters

This rule checks that Create methods have no optional parameters other than parameters defined in AEP-133 or other AEPs.

Details

This rule looks at the parameters of “post” operations on a path that does not have a ”:” in its final segment (indicating a custom operation), and complains if it finds any optional query parameters that are described in the AEPs. Currently the only allowed optional query parameter is id, described in AEP-133.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    post:
      parameters:
        - name: force
          in: query
          schema:
            type: boolean

Correct code for this rule:

paths:
  '/test1/{testId}/test2':
    post:
      parameters:
        - name: testId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: query
          schema:
            type: string

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/test1/post/parameters/0'
    rules:
      aep-133-unknown-optional-params: 'off'

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