openapi: 3.1.0
info:
  title: Orders API
  description: 'This is a template APIs.json for a orders 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: Orders
  description: 'Placing and managing of orders placed for products.

    '
paths:
  /orders:
    get:
      operationId: getOrders
      summary: Retrieves Orders
      description: Returns a list of all orders for the authenticated user.
      security:
      - apiKeys: []
      tags:
      - Orders
      responses:
        '200':
          description: A list of orders
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapperResponseCollection'
              examples:
                OrderCollection:
                  $ref: '#/components/examples/OrderCollection'
            application/xml:
              schema:
                $ref: '#/components/schemas/WrapperResponseCollection'
              examples:
                OrderCollection:
                  $ref: '#/components/examples/OrderCollection'
        '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: createOrder
      summary: Orders Create Order
      description: Creating a new order for sending to a recipient.
      tags:
      - Orders
      security:
      - apiKeys: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order:
                $ref: '#/components/examples/Order'
          application/xml:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order:
                $ref: '#/components/examples/Order'
      responses:
        '201':
          description: Order Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleOrder:
                  $ref: '#/components/examples/SingleOrder'
            application/xml:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleOrder:
                  $ref: '#/components/examples/SingleOrder'
        '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'
  /orders/{orderId}:
    parameters:
    - $ref: '#/components/parameters/OrderId'
    get:
      summary: Orders Retrieve Order
      description: Returns the details of a specific order.
      operationId: getOrder
      tags:
      - Orders
      security:
      - apiKeys: []
      responses:
        '200':
          description: Order Details
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleOrder:
                  $ref: '#/components/examples/SingleOrder'
            application/xml:
              schema:
                $ref: '#/components/schemas/WrapperResponseObject'
              examples:
                SingleOrder:
                  $ref: '#/components/examples/SingleOrder'
        '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: Orders Update Order
      description: Updates a single order.
      operationId: updateOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order:
                $ref: '#/components/examples/Order'
          application/xml:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order:
                $ref: '#/components/examples/Order'
      security:
      - apiKeys: []
      tags:
      - Orders
      responses:
        '204':
          description: Order 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: Orders Delete Order
      description: Deletes a order.
      operationId: deleteOrder
      security:
      - apiKeys: []
      tags:
      - Orders
      responses:
        '204':
          description: Order 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'
  /orders/{orderId}/cancle:
    parameters:
    - $ref: '#/components/parameters/OrderId'
    put:
      summary: Orders Cancel Order
      description: Cancels a single order.
      operationId: sendOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order:
                $ref: '#/components/examples/Order'
          application/xml:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order:
                $ref: '#/components/examples/Order'
      security:
      - apiKeys: []
      tags:
      - Orders
      responses:
        '204':
          description: Order 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:
  parameters:
    OrderId:
      name: orderId
      in: path
      required: true
      description: The ID of the order 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
  responses:
    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.
    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.
    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.
    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.
    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.
    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.
    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.
  schemas:
    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
    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
    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/Order'
        links:
          $ref: '#/components/schemas/LinksSelf'
      xml:
        name: data
    LinksSelf:
      type: object
      description: A link to reference each order.
      required:
      - self
      properties:
        self:
          type: string
          description: A URL to order returned.
          format: uri
          minLength: 10
          maxLength: 2048
    Person:
      type: object
      description: A Schema.org compliant person object.
      xml:
        name: person
      required:
      - identifier
      - name
      properties:
        identifier:
          type: string
          format: uuid
          description: Unique identifier for the person.
          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 person.
          minLength: 10
          maxLength: 10
          example: Kin Lane
        descripton:
          type: string
          description: The description of the person.
          minLength: 10
          maxLength: 2500
          example: The peson behind API Evangelist.
        email:
          type: string
          description: An email for the person.
          minLength: 10
          maxLength: 2048
          example: info@example.com
    Order:
      type: object
      description: A Schema.org compliant order object.
      xml:
        name: order
      required:
      - identifier
      - orderNumber
      - orderStatus
      - orderDate
      - customer
      - orderedItems
      properties:
        identifier:
          type: string
          format: uuid
          description: Unique identifier for the order.
          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
        orderNumber:
          type: integer
          description: Number for the order.
          minLength: 10
          maxLength: 10
          example: 1001
        orderStatus:
          type: string
          description: The status of the order
          minLength: 10
          maxLength: 250
          example: Processing
        orderDate:
          type: string
          description: The date when the order was placed.
          minLength: 10
          maxLength: 10
          example: '2018-04-25T18:00:30+01:00'
        customer:
          $ref: '#/components/schemas/Person'
        orderedItems:
          type: array
          maxItems: 25
          minItems: 1
          description: The timezone of the order in the [IANA Time Zone Database format](https://www.iana.org/time-zones).
          items:
            $ref: '#/components/schemas/Product'
    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/Order'
        links:
          $ref: '#/components/schemas/LinksPagination'
      xml:
        name: data
    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
    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
  examples:
    SingleOrder:
      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/orders
    Order:
      value:
        sender: Jane Doe
        recipient: John Doe
        subjectOf: Meeting Later
        text: Please meet me at the market.
    OrderCollection:
      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/orders
          next: https://api.example.com/orders?page=2
  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: Orders API Landing Page
  url: http://example.com/orders