openapi: 3.1.0
info:

  title: API Pulse Publishing
  description: |
    This is the  API for publishing to the API pulse.

  version: 0.1.0

  contact:
    name: API Evangelist
    url: https://apievangelist.com
    email: info@apievangelist.com

  termsOfService: http://theapipulse.com//terms/

  license:
    name: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
    identifier: CC-BY-NC-SA-4.0

externalDocs:
  description: API Pulse
  url: http://theapipulse.com/

servers:

  - url: http://api.theapipulse.com
    description: The base URL for the API Pulse.

tags:

  - name: Signals
    description: |
      The overall signal.                                                                     

paths:

  /signals:
    post:
      operationId: submitSignal
      summary: API Pulse Submit Signal
      description: Submits an entire signal.
      tags:
        - Signals
      requestBody:
        required: true
        description: A valid signal schema.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Signal'
      responses:
        '201':
          description: People Pulse Submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submitted'
              examples:
                Submitted:
                  $ref: '#/components/examples/Submitted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:

  examples:

    SignalOne:
      description: Entire Signal One
      value:
        people:
          name: Kin Lane
          email: info@apievangelist.com
          role: API Evangelist
          countries:
            - US
        organization:
          name: API Evangelist
          countries:
            - US
          employees: 1
        sectors:
          industries:
            - Software Delivery
        access:
          internal: 500
          partner: 50
          public: 5
        distribution:
          publicPortal: 1
          internalPortal: 2
          gateway: 1
        authentication:
          basicAuth: false
          keys: true
          jwt: false
          oauth: false
        httpApis:
          producedCount: 150
          producedPercentage: 100
          consumeCount: 20
          consumePercentage: 100
          openApi: true
          designFirst: true
          openApiDocumentation: true
          openApiMockServers: true
          openApiSdks: true
          openApiTesting: true
          openApiSecurity: false
          openApiPortal: false
          openApiRespository: true
        graphQlApis:
          producedCount: 1
          producedPercentage: 5
          consumeCount: 1
          consumePercentage: 5
          internally: true
          externally: false
        eventDrivenApis:
          webhooksPublish: 1
          webhooksSubscribe: 1
          webSocketsProduce: 1
          webSocketsPublish: 1
          webSocketsSubscribe: 1
          kafkaProduce: 1
          kafkaPublish: 1
          kafkaSubscribe: 1
          asyncApi: true
          designFirst: true
          asyncApiDocumentation: true
          asyncApiMockServers: true
          asyncApiSdks: true
          asyncApiTesting: true
          asyncApiSecurity: true
          asyncApiPortal: true
          asyncApiRespository: true
        schema:
          data: true
          apis: true
          validation: true
          forms: true
          registry: true
          repository: true
        contracts:
          discovery: true
          portal: true
          repository: true
        experience:
          discovery: 10
          onboarding: 10
          quality: 10
          reliability: 10
          consistency: 10
          communication: 10
          automation: 10
          integration: 10
        properties:
          editor: 10
          documentation: 10
          mockServers: 10
          sdks: 10
          testing: 10
          security: 10
          versioning: 10
        plans:
          applications: true
          rateLimits: true
          chargeAccess: true
          usage: true
          report: true
        governance:
          spectral: true
          vacuum: true
          design: true
          development: true
          pipelines: true
          gateway: true

    PeopleOne:
      description: People one.
      value:
        name: Kin Lane
        email: info@apievangelist.com
        role: API Evangelist
        countries:
          - US

    OrganizationOne:
      description: Organization one.
      value:
        name: API Evangelist
        countries:
          - US
        employees: 1

    SectorOne:
      description: Sector one.
      value:
        industries:
          - Software Delivery

    AccessOne:
      description: Access one.
      value:
        internal: 500
        partner: 50
        public: 5

    DistributionOne:
      description: Distribution one.
      value:
        publicPortal: 1
        internalPortal: 2
        gateway: 1

    AuthenticationOne:
      description: Authentication one.
      value:
        basicAuth: false
        keys: true
        jwt: false
        oauth: false

    HttpApisOne:
      description: HTTP APIs one.
      value:
        producedCount: 150
        producedPercentage: 100
        consumeCount: 20
        consumePercentage: 100
        openApi: true
        designFirst: true
        openApiDocumentation: true
        openApiMockServers: true
        openApiSdks: true
        openApiTesting: true
        openApiSecurity: false
        openApiPortal: false
        openApiRespository: true

    GraphQlApisOne:
      description: GraphQL APIs one.
      value:
        producedCount: 1
        producedPercentage: 5
        consumeCount: 1
        consumePercentage: 5
        internally: true
        externally: false

    EventDrivenApisOne:
      description: Event-Driven APIs one.
      value:
        webhooksPublish: 1
        webhooksSubscribe: 1
        webSocketsProduce: 1
        webSocketsPublish: 1
        webSocketsSubscribe: 1
        kafkaProduce: 1
        kafkaPublish: 1
        kafkaSubscribe: 1
        asyncApi: true
        designFirst: true
        asyncApiDocumentation: true
        asyncApiMockServers: true
        asyncApiSdks: true
        asyncApiTesting: true
        asyncApiSecurity: true
        asyncApiPortal: true
        asyncApiRespository: true

    SchemaOne:
      description: Schema one.
      value:
        data: true
        apis: true
        validation: true
        forms: true
        registry: true
        repository: true

    ContractOne:
      description: Contract one.
      value:
        discovery: true
        portal: true
        repository: true

    ExperienceOne:
      description: Experience one.
      value:
        discovery: 10
        onboarding: 10
        quality: 10
        reliability: 10
        consistency: 10
        communication: 10
        automation: 10
        integration: 10

    PropertiesOne:
      description: Properties one.
      value:
        editor: 10
        documentation: 10
        mockServers: 10
        sdks: 10
        testing: 10
        security: 10
        versioning: 10

    PlanOne:
      description: Plan one.
      value:
        applications: true
        rateLimits: true
        chargeAccess: true
        usage: true
        report: true

    GovernanceOne:
      description: Governance one.
      value:
        spectral: true
        vacuum: true
        design: true
        development: true
        pipelines: true
        gateway: true

    Submitted:
      description: Submitted
      value:
        message: The people pulse was submitted.

  schemas:

    Signal:
      type: object
      description: A pulse signal.
      required:
        - access
        - authentication
        - contracts
        - distribution
        - eventDrivenApis
        - experience
        - governance
        - graphQlApis
        - httpApis
        - organization
        - people
        - plans
        - properties
        - schema
        - sector
      properties:
        access:
          $ref: '#/components/schemas/Access'
        authentication:
          $ref: '#/components/schemas/Authentication'
        contracts:
          $ref: '#/components/schemas/Contract'
        distribution:
          $ref: '#/components/schemas/Distribution'
        eventDrivenApis:
          $ref: '#/components/schemas/EventDrivenApi'
        experience:
          $ref: '#/components/schemas/Experience'
        governance:
          $ref: '#/components/schemas/Governance'
        graphQlApis:
          $ref: '#/components/schemas/GraphQlApi'
        httpApis:
          $ref: '#/components/schemas/HttpApi'
        organization:
          $ref: '#/components/schemas/Organization'
        people:
          $ref: '#/components/schemas/People'
        plans:
          $ref: '#/components/schemas/Plan'
        properties:
          $ref: '#/components/schemas/Properties'
        schema:
          $ref: '#/components/schemas/Schema'
        sector:
          $ref: '#/components/schemas/Sector'

    People:
      type: object
      description: Pulse of the people.
      required:
        - name
        - email
        - role
        - countries
      properties:
        name:
          type: string
          description: A name.
          minLength: 5
          maxLength: 250
          example: Kin Lane
        email:
          type: string
          description: Valid email address.
          minLength: 1
          maxLength: 500
          example: info@apievangelist.com
        role:
          type: string
          description: Role of the person.
          minLength: 10
          maxLength: 250
          example: Evangelist
        linkedIn:
          type: string
          description: Valid LinkedIn URL.
          minLength: 10
          maxLength: 500
          example: https://www.linkedin.com/in/kinlane/
        countries:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 10
          description: A valid ISO 3166 country for the person.
          example:
            - US
        other:
          type: string
          description: Other information (People).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Organization:
      type: object
      description: Pulse of the organization.
      required:
        - employees
      properties:
        name:
          type: string
          description: The company name.
          minLength: 1
          maxLength: 500
          example: API Evangelist
        countries:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 10
          description: A valid ISO 3166 country for the organization.
          example:
            - US
        employees:
          type: integer
          description: The number of employees that work at an enterprise organization.
          minLength: 1
          maxLength: 500000
          example: 100
        other:
          type: string
          description: Other information (Organization).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Sector:
      type: object
      description: Pulse of the sector.
      required:
        - industries
      properties:
        industries:
          type: array
          items:
            type: string
            enum:
              - Technology
              - Healthcare & Pharmaceuticals
              - Finance & Insurance
              - Energy & Utilities
              - Retail & E-Commerce
              - Automotive & Transportation
              - Construction & Real Estate
              - Media & Entertainment
              - Manufacturing & Industrial Production
              - Telecommunications
              - Food & Beverage
              - Agriculture & Agribusiness
              - Education & EdTech
              - Aerospace & Defense
              - Hospitality & Tourism
              - Chemicals & Materials
              - Biotechnology & Life Sciences
              - Environmental & Sustainability
              - Legal & Professional Services
              - Sports & Recreation
              - Mining & Metals
              - Fashion & Apparel
              - Supply Chain & Logistics
              - Nonprofit & Philanthropy
              - Government
          minItems: 1
          maxItems: 10
          description: A valid North American Industry Classification System (NAICS) entry.
          example:
            - Technology

    Access:
      type: object
      description: Pulse of access.
      required:
        - internal
        - partner
        - public
      properties:
        internal:
          type: integer
          description: How many internal APIs do you produce?
          minLength: 0
          maxLength: 50000
          example: 2500
        partner:
          type: integer
          description: How many partner APIs do you produce?
          minLength: 0
          maxLength: 50000
          example: 50
        public:
          type: integer
          description: How many public APIs do you produce?
          minLength: 0
          maxLength: 50000
          example: 50
        other:
          type: string
          description: Other information (Access).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Distribution:
      type: object
      description: Pulse of distribution.
      required:
        - publicPortal
      properties:
        publicPortal:
          type: integer
          description: How many public API portals do you have?
          minLength: 0
          maxLength: 25
          example: 1
        internalPortal:
          type: integer
          description: How many internal API portals do you have?
          minLength: 0
          maxLength: 25
          example: 1
        gateway:
          type: integer
          description: How many API gateways do you have?
          minLength: 0
          maxLength: 25
          example: 2
        other:
          type: string
          description: Other information (Distribution).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Authentication:
      type: object
      description: Pulse of authentication.
      required:
        - basicAuth
        - keys
        - jwt
        - oauth
      properties:
        basicAuth:
          type: boolean
          description: Do you use BasicAuth to authenticate with APIs?
          example: true
        keys:
          type: boolean
          description: Do you use API keys to authenticate with APIs?
          example: true
        jwt:
          type: boolean
          description: HDo you use JWT to authenticate with APIs?
          example: true
        oauth:
          type: boolean
          description: Do you use OAuth to authenticate with APIs?
          example: true
        other:
          type: string
          description: Other information (Authentication).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    HttpApi:
      type: object
      description: Pulse of HTTP APIs.
      required:
        - producedCount
        - producedPercentage
        - consumeCount
        - consumePercentage
        - openApi
        - designFirst
        - openApiDocumentation
        - openApiMockServers
        - openApiSdks
        - openApiTesting
        - openApiSecurity
        - openApiPortal
        - openApiRespository
      properties:
        producedCount:
          type: integer
          description: How many HTTP APIs do you produce?
          minLength: 0
          maxLength: 10000
          example: 500
        producedPercentage:
          type: integer
          description: What percentage of APIs you produce are HTTP APIs?
          minLength: 0
          maxLength: 100
          example: 50
        consumeCount:
          type: integer
          description: How many HTTP APIs do you consume?
          minLength: 0
          maxLength: 1000
          example: 25
        consumePercentage:
          type: integer
          description: What percentage of APIs you consume are HTTP APIs?
          minLength: 0
          maxLength: 100
          example: 90
        openApi:
          type: boolean
          description: Do you use OpenAPI?
          example: true
        designFirst:
          type: boolean
          description: Are you design-first when producing HTTP APIs?
          example: true
        openApiDocumentation:
          type: boolean
          description: Do you use OpenAPI for Generating Documentation?
          example: true
        openApiMockServers:
          type: boolean
          description: Do you use OpenAPI for Generating Mock Servers?
          example: true
        openApiSdks:
          type: boolean
          description: Do you use OpenAPI for Software Development Kits (SDKs)?
          example: true
        openApiTesting:
          type: boolean
          description: Do you use OpenAPI for Testing?
          example: true
        openApiSecurity:
          type: boolean
          description: Do you use OpenAPI for Security?
          example: true
        openApiPortal:
          type: boolean
          description: Do you publish OpenAPI to a portal?
          example: true
        openApiRespository:
          type: boolean
          description: Do you publish OpenAPI to a repository?
          example: true
        other:
          type: string
          description: Other information (HTTP APIs).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    GraphQlApi:
      type: object
      description: Pulse of GraphQL APIs.
      required:
        - producedCount
        - producedPercentage
        - consumeCount
        - consumePercentage
        - internally
        - externally
      properties:
        producedCount:
          type: integer
          description: How many GraphQL APIs do you produce?
          minLength: 0
          maxLength: 10000
          example: 500
        producedPercentage:
          type: integer
          description: What percentage of the  APIs you produce are GraphQL?
          minLength: 0
          maxLength: 100
          example: 50
        consumeCount:
          type: integer
          description: How many GraphQL APIs do you consume?
          minLength: 0
          maxLength: 1000
          example: 25
        consumePercentage:
          type: integer
          description: What percentage of the APIs you consume are GraphQL APIs?
          minLength: 0
          maxLength: 100
          example: 90
        internally:
          type: boolean
          description: Do you use GraphQL internally?
          example: true
        externally:
          type: boolean
          description: Do you use GraphQL externally?
          example: true
        other:
          type: string
          description: Other information (GraphQL APIs).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    EventDrivenApi:
      type: object
      description: Pulse of Event-Driven APIs.
      required:
        - webhooksPublish
        - webhooksSubscribe
        - webSocketsProduce
        - webSocketsPublish
        - webSocketsSubscribe
        - kafkaProduce
        - kafkaPublish
        - kafkaSubscribe
        - asyncApi
        - designFirst
        - asyncApiDocumentation
        - asyncApiMockServers
        - asyncApiSdks
        - asyncApiTesting
        - asyncApiSecurity
        - asyncApiPortal
        - asyncApiRespository
      properties:
        webhooksPublish:
          type: integer
          description: How many Webhooks to you publish?
          minLength: 0
          maxLength: 10000
          example: 500
        webhooksSubscribe:
          type: integer
          description: How many Webhooks to you subscribe?
          minLength: 0
          maxLength: 1000
          example: 25
        webSocketsProduce:
          type: integer
          description: How many WebSockets to you produce?
          minLength: 0
          maxLength: 10000
          example: 500
        webSocketsPublish:
          type: integer
          description: How many WebSockets to you publish to?
          minLength: 0
          maxLength: 10000
          example: 500
        webSocketsSubscribe:
          type: integer
          description: How many WebSockets to you subscribe to?
          minLength: 0
          maxLength: 1000
          example: 25
        kafkaProduce:
          type: integer
          description: How many Kafka APIs to you produce?
          minLength: 0
          maxLength: 10000
          example: 500
        kafkaPublish:
          type: integer
          description: How many Kafka APIs to you publish to?
          minLength: 0
          maxLength: 10000
          example: 500
        kafkaSubscribe:
          type: integer
          description: How many Kafka APIs to you subscribe to?
          minLength: 0
          maxLength: 1000
          example: 25
        asyncApi:
          type: boolean
          description: Do you use AsyncAPI?
          example: true
        designFirst:
          type: boolean
          description: Are you design-first when producing event-driven APIs?
          example: true
        asyncApiDocumentation:
          type: boolean
          description: Do you use AsyncAPI for Generating Documentation?
          example: true
        asyncApiMockServers:
          type: boolean
          description: Do you use AsyncAPI for Generating Mock Servers?
          example: true
        asyncApiSdks:
          type: boolean
          description: Do you use AsyncAPI for Software Development Kits (SDKs)?
          example: true
        asyncApiTesting:
          type: boolean
          description: Do you use AsyncAPI for Testing?
          example: true
        asyncApiSecurity:
          type: boolean
          description: Do you use AsyncAPI for Security?
          example: true
        asyncApiPortal:
          type: boolean
          description: Do you publish AsyncAPI to a portal?
          example: true
        asyncApiRespository:
          type: boolean
          description: Do you publish AsyncAPI to a repository?
          example: true
        other:
          type: string
          description: Other information (Event-Driven APIs).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Schema:
      type: object
      description: Pulse of schema.
      required:
        - data
        - apis
        - validation
        - forms
        - registry
        - repository
      properties:
        data:
          type: boolean
          description: Do you use JSON Schema to define data?
          example: true
        apis:
          type: boolean
          description: Do you use JSON Schema to define APIs?
          example: true
        validation:
          type: boolean
          description: Do you use JSON Schema to validate data?
          example: true
        forms:
          type: boolean
          description: Do you use JSON Schema to generate forms?
          example: true
        registry:
          type: boolean
          description: Do you publish JSON Schema to registry?
          example: true
        repository:
          type: boolean
          description: Do you publish JSON Schema to repository?
          example: true
        other:
          type: string
          description: Other information (Schema).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Contract:
      type: object
      description: Pulse of contract.
      required:
        - discovery
        - portal
        - repository
      properties:
        discovery:
          type: boolean
          description: Do you use APIs.json for discovery?
          example: true
        portal:
          type: boolean
          description: Do you publish APIs.json to portal?
          example: true
        repository:
          type: boolean
          description: Do you publish APIs.json to repository?
          example: true
        other:
          type: string
          description: Other information (Contract).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Experience:
      type: object
      description: Pulse of experience.
      required:
        - discovery
        - onboarding
        - quality
        - reliability
        - consistency
        - communication
      properties:
        discovery:
          type: integer
          description: How much of a priority is API discovery?
          example: 10
          minLength: 3
          maxLength: 3
        onboarding:
          type: integer
          description: How much of a priority is API onboarding?
          example: 10
          minLength: 3
          maxLength: 3
        quality:
          type: integer
          description: How much of a priority is API quality?
          example: 10
          minLength: 3
          maxLength: 3
        reliability:
          type: integer
          description: How much of a priority is API reliability?
          example: 10
          minLength: 3
          maxLength: 3
        consistency:
          type: integer
          description: How much of a priority is API consistency?
          example: 10
          minLength: 3
          maxLength: 3
        communication:
          type: integer
          description: How much of a priority is API communication?
          example: 10
          minLength: 3
          maxLength: 3
        automation:
          type: integer
          description: How much of a priority is API automation?
          example: 10
          minLength: 3
          maxLength: 3
        integration:
          type: integer
          description: How much of a priority is API integration?
          example: 10
          minLength: 3
          maxLength: 3
        other:
          type: string
          description: Other information (Experience).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Properties:
      type: object
      description: Pulse of API operational properties.
      required:
        - documentation
        - mockServers
        - sdks
        - testing
        - security
      properties:
        documentation:
          type: integer
          description: How much of a priority is API documentation?
          example: 10
          minLength: 3
          maxLength: 3
        mockServers:
          type: integer
          description: How much of a priority is API mock servers?
          example: 10
          minLength: 3
          maxLength: 3
        sdks:
          type: integer
          description: How much of a priority is SDKs?
          example: 10
          minLength: 3
          maxLength: 3
        testing:
          type: integer
          description: How much of a priority is API testing?
          example: 10
          minLength: 3
          maxLength: 3
        security:
          type: integer
          description: How much of a priority is API security?
          example: 10
          minLength: 3
          maxLength: 3
        versioning:
          type: integer
          description: How much of a priority is API versioning?
          example: 10
          minLength: 3
          maxLength: 3
        other:
          type: string
          description: Other information (Properties).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Plan:
      type: object
      description: Pulse of API planning.
      required:
        - applications
        - rateLimits
        - chargeAccess
        - usage
        - report
      properties:
        applications:
          type: boolean
          description: Do you require an application to be defined to access APIs?
          example: true
        rateLimits:
          type: boolean
          description: Do you enforce rate limits across all APIs?
          example: true
        chargeAccess:
          type: boolean
          description: Do you charge for access to any APIs?
          example: true
        usage:
          type: boolean
          description: Do you monitor API usage for APIs in production?
          example: true
        report:
          type: boolean
          description: Do you report on API usage data with consumers?
          example: true
        other:
          type: string
          description: Other information (Plan).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Governance:
      type: object
      description: Pulse of API governance.
      required:
        - spectral
        - vacuum
        - design
        - development
        - pipelines
        - gateway
      properties:
        spectral:
          type: boolean
          description: Do you use Spectral for governance rules?
          example: true
        vacuum:
          type: boolean
          description: Do you use Vacuum for governance?
          example: true
        design:
          type: boolean
          description: Do you apply rules during design of APIs?
          example: true
        development:
          type: boolean
          description: Do you apply rules during development of APIs?
          example: true
        pipelines:
          type: boolean
          description: Do you apply rules during pipeline builds of APIs?
          example: true
        gateway:
          type: boolean
          description: Do you validate JSON Schema at the API gateway?
          example: true
        other:
          type: string
          description: Other information (Governance).
          minLength: 10
          maxLength: 250
          example: Something additional I wanted to say.

    Submitted:
      type: object
      description: The submitted pulse.
      required:
        - message
      properties:
        message:
          type: string
          minLength: 10
          maxLength: 50
          description: The message being returned.
          example: The people pulse was submitted.

    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: 5
          maxLength: 250
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
          example: A valid 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

  headers:

    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

    Retry-After:
      description: |
        The Retry-After header indicates how long the user agent should wait before making a follow-up request. 
        The value is in seconds and can be an integer or a date in the future. 
        If the value is an integer, it indicates the number of seconds to wait. 
        If the value is a date, it indicates the time at which the user agent should make a follow-up request. 
      schema:
        type: string
        minLength: 2
        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

  responses:

    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.

    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.

    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.