openapi: 3.1.0
info:
  title: 'Drupal JSON: Comments Node Pages API'
  description: The Drupal JSON:API module is a core component that exposes all Drupal entity types and bundles as a standards-compliant JSON:API interface, requiring no configuration to enable. Each entity bundle receives a unique URL path following the pattern /jsonapi/{entity_type}/{bundle}, and the module supports GET, POST, PATCH, and DELETE operations for full CRUD access. It supports filtering, sorting, pagination, sparse fieldsets, includes for relationship resolution, translations, revisions, and file uploads out of the box. All resource identifiers use entity UUIDs rather than numeric IDs. The JSON:API module is the recommended approach for most decoupled and headless Drupal applications due to its adherence to the open JSON:API specification (jsonapi.org) and its compatibility with the broader JSON:API client ecosystem.
  version: '1.1'
  contact:
    name: Drupal Community
    url: https://www.drupal.org/community
  termsOfService: https://www.drupal.org/about/legal
servers:
- url: https://example.com/jsonapi
  description: Drupal JSON:API Base (replace with your Drupal installation base URL)
security:
- basicAuth: []
- oAuth2:
  - content
tags:
- name: Node Pages
  description: JSON:API endpoints for basic page content nodes. The bundle slug varies by Drupal installation.
paths:
  /node/page:
    get:
      operationId: listNodePages
      summary: List basic page nodes
      description: Retrieves a collection of basic page content nodes. Supports the same query parameters as other JSON:API collection endpoints including filter, sort, page, include, and fields.
      tags:
      - Node Pages
      parameters:
      - $ref: '#/components/parameters/JsonApiAccept'
      - $ref: '#/components/parameters/FilterPath'
      - $ref: '#/components/parameters/FilterValue'
      - $ref: '#/components/parameters/SortParam'
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/IncludeParam'
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Collection of basic page nodes returned successfully.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JsonApiCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
  /node/page/{uuid}:
    get:
      operationId: getNodePage
      summary: Get a basic page node
      description: Retrieves a single basic page content node by its UUID. Supports sparse fieldsets and relationship includes.
      tags:
      - Node Pages
      parameters:
      - $ref: '#/components/parameters/EntityUuid'
      - $ref: '#/components/parameters/JsonApiAccept'
      - $ref: '#/components/parameters/IncludeParam'
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Basic page node returned successfully.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JsonApiSingleResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: The request body or query parameters are invalid.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorResponse'
    NotFound:
      description: The requested resource does not exist or is inaccessible.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorResponse'
    Forbidden:
      description: The authenticated user lacks permission to perform this operation.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorResponse'
  parameters:
    FilterPath:
      name: filter[name][path]
      in: query
      required: false
      description: The dotted field path to filter on, e.g. title, status, uid.name, or field_tags.name for nested relationship fields.
      schema:
        type: string
        example: status
    FieldsParam:
      name: fields[node--article]
      in: query
      required: false
      description: Sparse fieldset parameter to limit which attributes are returned, reducing response payload size. Replace node--article with the relevant resource type. Value is a comma-separated list of field names.
      schema:
        type: string
        example: title,body,created
    PageLimit:
      name: page[limit]
      in: query
      required: false
      description: The maximum number of resources to return in a single page. Used for cursor-based pagination.
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 50
    EntityUuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the entity. JSON:API always uses UUID as the identifier, not the numeric entity ID.
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
    SortParam:
      name: sort
      in: query
      required: false
      description: Sort the results by the given field. Prefix with - for descending order. For example, sort=title for ascending by title or sort=-created for descending by creation date.
      schema:
        type: string
        example: -created
    JsonApiAccept:
      name: Accept
      in: header
      required: false
      description: The JSON:API media type. Include this header to receive a properly formatted JSON:API response.
      schema:
        type: string
        default: application/vnd.api+json
    FilterValue:
      name: filter[name][value]
      in: query
      required: false
      description: The value to filter against.
      schema:
        type: string
        example: '1'
    PageOffset:
      name: page[offset]
      in: query
      required: false
      description: The number of resources to skip before beginning to return results. Used in combination with page[limit] for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    IncludeParam:
      name: include
      in: query
      required: false
      description: A comma-separated list of relationship paths to include in the response. For example, include=uid resolves the author relationship, and include=field_tags includes related taxonomy terms inline.
      schema:
        type: string
        example: uid,field_tags
  schemas:
    JsonApiLinks:
      type: object
      description: Navigation links included in JSON:API responses.
      properties:
        self:
          type: object
          description: Link to the current resource or collection.
          properties:
            href:
              type: string
              format: uri
              description: The URL of the current resource.
        related:
          type: object
          description: Link to a related resource.
          properties:
            href:
              type: string
              format: uri
              description: The URL of the related resource.
    JsonApiSingleResponse:
      type: object
      description: A JSON:API response containing a single resource object.
      properties:
        jsonapi:
          type: object
          description: JSON:API version metadata.
          properties:
            version:
              type: string
              description: The JSON:API specification version.
              example: '1.0'
        data:
          $ref: '#/components/schemas/JsonApiResourceObject'
        included:
          type: array
          description: Array of included related resources when using the include parameter.
          items:
            $ref: '#/components/schemas/JsonApiResourceObject'
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    JsonApiErrorResponse:
      type: object
      description: A JSON:API error response containing one or more error objects.
      properties:
        errors:
          type: array
          description: Array of error objects describing the problems encountered.
          items:
            $ref: '#/components/schemas/JsonApiError'
        jsonapi:
          type: object
          properties:
            version:
              type: string
              example: '1.0'
    JsonApiCollection:
      type: object
      description: A JSON:API collection response containing multiple resource objects.
      properties:
        jsonapi:
          type: object
          description: JSON:API version metadata.
          properties:
            version:
              type: string
              description: The JSON:API specification version.
              example: '1.0'
        data:
          type: array
          description: Array of resource objects.
          items:
            $ref: '#/components/schemas/JsonApiResourceObject'
        included:
          type: array
          description: Array of included related resources when using the include parameter.
          items:
            $ref: '#/components/schemas/JsonApiResourceObject'
        links:
          $ref: '#/components/schemas/JsonApiCollectionLinks'
        meta:
          type: object
          description: Non-standard meta-information about the response, such as total result count.
          properties:
            count:
              type: integer
              description: Total number of matching resources across all pages.
    JsonApiResourceObject:
      type: object
      description: A JSON:API resource object representing a single Drupal entity.
      required:
      - type
      - id
      properties:
        type:
          type: string
          description: The JSON:API resource type in the format {entity_type}--{bundle}, e.g. node--article, taxonomy_term--tags.
          example: node--article
        id:
          type: string
          format: uuid
          description: The UUID of the resource.
        attributes:
          type: object
          description: The resource's field values excluding entity references. Keys are field machine names.
        relationships:
          type: object
          description: The resource's entity reference fields expressed as relationship objects with data containing type and id.
        links:
          $ref: '#/components/schemas/JsonApiLinks'
    JsonApiError:
      type: object
      description: A single JSON:API error object.
      properties:
        status:
          type: string
          description: The HTTP status code for this error.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        detail:
          type: string
          description: A human-readable explanation specific to this error occurrence.
        source:
          type: object
          description: An object containing a reference to the source of the error.
          properties:
            pointer:
              type: string
              description: A JSON Pointer to the associated entity in the request body.
            parameter:
              type: string
              description: The query parameter that caused the error.
    JsonApiCollectionLinks:
      type: object
      description: Pagination links for collection responses.
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the current page.
        first:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the first page of results.
        prev:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the previous page of results.
        next:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the next page of results.
        last:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: Link to the last page of results.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Drupal username and password.
    cookieAuth:
      type: apiKey
      in: cookie
      name: SESS
      description: Cookie-based session authentication obtained via Drupal login.
    oAuth2:
      type: oauth2
      description: OAuth 2.0 via the Simple OAuth module.
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            content: Access and manage content entities
            user: Access and manage user entities
externalDocs:
  description: Drupal JSON:API Module Documentation
  url: https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module/api-overview