readeck/docs/api/traits.yaml

---
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
#
# SPDX-License-Identifier: AGPL-3.0-only

public:
  security: []
  x-badges:
    - color: green
      label: public

admin-only:
  x-badges:
    - color: red
      label: admin only

scope-bookmarks-read:
  x-badges:
    - color: blue
      label: "oauth | bookmarks:read"

scope-bookmarks-write:
  x-badges:
    - color: blue
      label: "oauth | bookmarks:write"

scope-profile-read:
  x-badges:
    - color: blue
      label: "oauth | profile:read"

authenticated:
  responses:
    "401":
      description: |
        Unauthorized. The request token found in the Authorization header is not valid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/message"
    "403":
      description: |
        Forbidden. The user doesn't have permission to perform the request but has other permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/message"

paginated:
  x-badges:
    - color: purple
      label: paginated

  parameters:
    - name: limit
      in: query
      description: Number of items per page
      schema:
        type: integer
    - name: offset
      in: query
      description: Pagination offset
      schema:
        type: integer

  responses:
    '200':
      headers:
        Link:
          description: Link to other pages in paginated results
          schema:
            type: array
            items:
              type: string
        Current-Page:
          description: Current page number
          schema:
            type: integer
        Total-Count:
          description: Total number of items
          schema:
            type: integer
        Total-Pages:
          description: Total number of pages
          schema:
            type: integer

created:
  responses:
    "201":
      headers:
        Location:
          description: URL of the created resource
          schema:
            type: string
            format: uri
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/message"

deferred:
  responses:
    "202":
      headers:
        Location:
          description: URL of the created resource
          schema:
            type: string
            format: uri
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/message"

validator:
  responses:
    "422":
      description: |
        This HTTP response is sent when the input data is not valid. It contains an object
        with all the detected errors.
      content:
        application/json:
          schema:
            properties:
              is_valid:
                type: boolean
                description: |
                  `true` if the input is valid
              errors:
                type: "[string]"
                nullable: true
                description: List of global input errors
              fields:
                type: object
                description: |
                  All the fields, with and without errors
                additionalProperties:
                  properties:
                    is_null:
                      type: boolean
                      description: |
                        `true` if the input value is null
                    is_bound:
                      type: boolean
                      description: |
                        `true` when the value is bound to the form
                    value:
                      type: any
                      description: Item's value; can be any type
                    errors:
                      type: "[string]"
                      nullable: true
                      description: List of errors for this field