openapi: 3.1.0
info:
  title: Products API
  description: 'This is a template APIs.json for a products API, to be used in storytelling, training, and knowledge bases.

    '
  version: 0.1.0
  contact:
    name: API Evangelist
    url: https://apievangelist.com
    email: info@apievangelist.com
  termsOfService: http://example.com/terms/
  license:
    name: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
    identifier: CC-BY-NC-SA-4.0
    url: https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en
servers:
- url: https://api.example.com
  description: Production
tags:
- name: Products
  description: 'Placing and managing of products placed for products.

    '
paths:
  /products:
    get:
      operationId: getProducts
      summary: Retrieves Products
      description: Returns a list of all products for the authenticated user.
      security:
      - apiKeys: []
      tags:
      - Products
      responses:
        '200':
          description: A list of products
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapperResponseCollection'
              examples:
                ProductCollection:
                  $ref: '#/components/examples/ProductCollection'
            application/xml:
              schema:
                $ref: '#/components/schemas/WrapperResponseCollection'
              examples:
                ProductCollection:
                  $ref: '#/components/examples/ProductCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createProduct
      summary: Products Create Product
      description: Creating a new product for sending to a recipient.
      tags:
      - Products
      security:
      - apiKeys: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              Product:
                $ref: '#/components/examples/Product'
          application/xml:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              Product:
                $ref: '#/components/examples/Product'
      responses:
        '201':
          description: Product Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleProduct:
                  $ref: '#/components/examples/SingleProduct'
            application/xml:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleProduct:
                  $ref: '#/components/examples/SingleProduct'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /products/{productId}:
    parameters:
    - $ref: '#/components/parameters/ProductId'
    get:
      summary: Products Retrieve Product
      description: Returns the details of a specific product.
      operationId: getProduct
      tags:
      - Products
      security:
      - apiKeys: []
      responses:
        '200':
          description: Product Details
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleProduct:
                  $ref: '#/components/examples/SingleProduct'
            application/xml:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleProduct:
                  $ref: '#/components/examples/SingleProduct'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      summary: Products Update Product
      description: Updates a single product.
      operationId: updateProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              Product:
                $ref: '#/components/examples/Product'
          application/xml:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              Product:
                $ref: '#/components/examples/Product'
      security:
      - apiKeys: []
      tags:
      - Products
      responses:
        '204':
          description: Product Updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Products Delete Product
      description: Deletes a product.
      operationId: deleteProduct
      security:
      - apiKeys: []
      tags:
      - Products
      responses:
        '204':
          description: Product Deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /products/{productId}/cancle:
    parameters:
    - $ref: '#/components/parameters/ProductId'
    put:
      summary: Products Cancel Product
      description: Cancels a single product.
      operationId: sendProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              Product:
                $ref: '#/components/examples/Product'
          application/xml:
            schema:
              $ref: '#/components/schemas/Product'
            examples:
              Product:
                $ref: '#/components/examples/Product'
      security:
      - apiKeys: []
      tags:
      - Products
      responses:
        '204':
          description: Product Sent
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    LinksSelf:
      type: object
      description: A link to reference each product.
      required:
      - self
      properties:
        self:
          type: string
          description: A URL to product returned.
          format: uri
          minLength: 10
          maxLength: 2048
    Meta:
      type: object
      description: The metadata for each response.
      required:
      - page
      - totalPages
      properties:
        page:
          type: integer
          description: The page represented in response.
          minLength: 1
          maxLength: 1000
        pageSize:
          type: integer
          minLength: 1
          maxLength: 1000
          description: The overall page size limits.
        totalPages:
          type: integer
          description: The total number of pages.
          minLength: 1
          maxLength: 1000
    WrapperResponseCollection:
      description: This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS).
      type: object
      required:
      - meta
      - data
      - links
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          description: The wrapper for a collection is an array of objects.
          type: array
          maxItems: 100
          minItems: 1
          items:
            $ref: '#/components/schemas/Product'
        links:
          $ref: '#/components/schemas/LinksPagination'
      xml:
        name: data
    Product:
      type: object
      description: A Schema.org compliant product object.
      xml:
        name: product
      required:
      - identifier
      - name
      - description
      properties:
        identifier:
          type: string
          format: uuid
          description: Unique identifier for the product.
          minLength: 36
          maxLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          example: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
        name:
          type: integer
          description: Name of the product.
          minLength: 10
          maxLength: 10
          example: Example Product
        descripton:
          type: string
          description: The description of the product.
          minLength: 10
          maxLength: 2500
          example: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
        image:
          type: string
          description: An image for the organization.
          minLength: 10
          maxLength: 2048
          example: http://example.com/image.jpg
    Problem:
      type: object
      description: This is a Problem Details for HTTP APIs object.
      required:
      - title
      - status
      xml:
        name: problem
        namespace: urn:ietf:rfc:7807
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type
          example: https://example.com/probs/out-of-credit
          minLength: 10
          maxLength: 2048
        title:
          type: string
          description: A short, human-readable summary of the problem type
          example: You do not have enough credit.
          minLength: 10
          maxLength: 250
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
          example: Your current balance is 30, but that costs 50.
          minLength: 10
          maxLength: 1000
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
          example: /account/12345/msgs/abc
          minLength: 10
          maxLength: 250
        status:
          type: integer
          description: The HTTP status code
          example: 400
          minLength: 3
          maxLength: 3
    WrapperResponseObject:
      description: This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS).
      type: object
      required:
      - meta
      - data
      - links
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/Product'
        links:
          $ref: '#/components/schemas/LinksSelf'
      xml:
        name: data
    LinksPagination:
      type: object
      description: The handling of each page.
      properties:
        next:
          type: string
          description: The next page in results.
          format: uri
          minLength: 10
          maxLength: 2048
        prev:
          type: string
          description: The previous page in results.
          format: uri
          minLength: 10
          maxLength: 2048
  parameters:
    ProductId:
      name: productId
      in: path
      required: true
      description: The ID of the product to retrieve.
      schema:
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      example: 1725ff48-ab45-4bb5-9d02-88745177dedb
  examples:
    Product:
      value:
        sender: Jane Doe
        recipient: John Doe
        subjectOf: Meeting Later
        text: Please meet me at the market.
    ProductCollection:
      value:
        meta:
          page: 1
          pageSize: 10
          totalPages: 2
        data:
        - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
          sender: Jane Doe
          recipient: John Doe
          subjectOf: Meeting Later
          text: Please meet me at the market.
          dateSent: '2018-04-25T18:00:30+01:00'
          dateReceived: '2018-04-25T18:00:30+01:00'
        links:
          self: https://api.example.com/products
          next: https://api.example.com/products?page=2
    SingleProduct:
      value:
        meta:
          page: 1
          pageSize: 10
          totalPages: 2
        data:
          id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
          sender: Jane Doe
          recipient: John Doe
          subjectOf: Meeting Later
          text: Please meet me at the market.
          dateSent: '2018-04-25T18:00:30+01:00'
          dateReceived: '2018-04-25T18:00:30+01:00'
        links:
          self: https://api.example.com/products
  responses:
    InternalServerError:
      description: Internal Server Error
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/internal-server-error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred.
        application/problem+xml:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/internal-server-error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred.
    Conflict:
      description: Conflict
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/conflict
            title: Conflict
            status: 409
            detail: There is a conflict with an existing resource.
        application/problem+xml:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/conflict
            title: Conflict
            status: 409
            detail: There is a conflict with an existing resource.
    Unauthorized:
      description: Unauthorized
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: You do not have the necessary permissions.
        application/problem+xml:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: You do not have the necessary permissions.
    BadRequest:
      description: Bad Request
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/bad-request
            title: Bad Request
            status: 400
            detail: The request is invalid or missing required parameters.
        application/problem+xml:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/bad-request
            title: Bad Request
            status: 400
            detail: The request is invalid or missing required parameters.
    Forbidden:
      description: Forbidden
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/forbidden
            title: Forbidden
            status: 403
            detail: Access is forbidden with the provided credentials.
        application/problem+xml:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/forbidden
            title: Forbidden
            status: 403
            detail: Access is forbidden with the provided credentials.
    NotFound:
      description: Not Found
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/not-found
            title: Not Found
            status: 404
            detail: The requested resource was not found.
        application/problem+xml:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/not-found
            title: Not Found
            status: 404
            detail: The requested resource was not found.
    TooManyRequests:
      description: Too Many Requests
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/too-many-requests
            title: Too Many Requests
            status: 429
            detail: You have exceeded the rate limit.
        application/problem+xml:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://example.com/errors/too-many-requests
            title: Too Many Requests
            status: 429
            detail: You have exceeded the rate limit.
  headers:
    Retry-After:
      description: "The Retry-After header indicates how long the user agent should wait before making a follow-up request. \nThe value is in seconds and can be an integer or a date in the future. \nIf the value is an integer, it indicates the number of seconds to wait. \nIf the value is a date, it indicates the time at which the user agent should make a follow-up request. \n"
      schema:
        type: string
        minLength: 10
        maxLength: 250
      examples:
        integer:
          value: '120'
          summary: Retry after 120 seconds
        date:
          value: Fri, 31 Dec 2021 23:59:59 GMT
          summary: Retry after the specified date
    RateLimit:
      description: 'The RateLimit header communicates quota policies. It contains a `limit` to

        convey the expiring limit, `remaining` to convey the remaining quota units,

        and `reset` to convey the time window reset time.

        '
      schema:
        type: string
        minLength: 10
        maxLength: 250
        example: limit=10, remaining=0, reset=10
  securitySchemes:
    apiKeys:
      type: apiKey
      name: api-key
      in: header
externalDocs:
  description: Products API Landing Page
  url: http://example.com/products