json-api/content-type

Since 0.0.1 · fixed by --fix · In the rulesets: JsonApi at error

This rule checks that every request body and response of the document declares the application/vnd.api+json media type.

Rule details

JSON:API clients and servers negotiate with the application/vnd.api+json media type; a document that declares application/json describes the same bytes, but hides that the API follows JSON:API from the tools that read it, and from the clients that send the Accept and Content-Type headers the specification requires.

The rule reports Request body media type is not application/vnd.api+json and Response media type is not application/vnd.api+json. It is part of the json-api ruleset and meant for APIs that follow JSON:API; turn it off for the others.

Examples

Good. The response says it is a JSON:API document.

openapi: 3.1.0
info:
  title: Users
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/UserListResponse"

Bad. A JSON:API document declared as plain JSON.

openapi: 3.1.0
info:
  title: Users
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"

Automatic fixes

--fix renames a content entry that is the only one and is application/json to application/vnd.api+json, keeping the rest of the media type. A content map with several entries is left for you to decide.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      json-api/content-type: off
Was this helpful?