registryapi.yml

openapi: 3.0.0
info:
  title: Registry APIs
  description: API Spec for the Registry Infrastructure
  version: 0.2.0
  license:
    name: CC-BY-ND
    url: 'https://github.com/beckn/protocol-specifications/blob/master/LICENSE.md'
paths:
  /subscribe:
    post:
      tags:
        - Registry
      description: Subscribe to a network
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriber_id:
                  type: string
                  description: |
                    A unique ID describing a subscriber on a network.
                    The typical format of a subscriber is as follows.
                    ``` <fqdn>.<extension>
                    ```
                    where, <br/>
                    <table> <thead>
                      <tr>
                        <td>Key</th>
                        <td>Description</th>
                      </tr>
                    </thead> <tbody>
                      <tr>
                        <td>fqdn</th>
                        <td>Fully qualified domain name</th>
                      </tr>
                      <tr>
                        <td>extn</td>
                        <td>Domain Extension</td>
                      </tr>
                    </tbody> </table>
                    The domain name of the subscriber must be an ```https``` domain with a ```.com``` extension and a valid SSL certificate from a trusted certificate authority of the country of operation
                  example: example.com
                country:
                  $ref: '#/components/schemas/Country/properties/code'
                city:
                  $ref: '#/components/schemas/City/properties/code'
                domain:
                  type: string
                signing_public_key:
                  type: string
                encr_public_key:
                  type: string
                valid_from:
                  type: string
                  format: date-time
                valid_until:
                  type: string
                  format: date-time
                nonce:
                  type: string
                  description: Random nonce. Must be unique to every request
      responses:
        '200':
          description: Registration status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - INITIATED
                      - UNDER_SUBSCRIPTION
                      - SUBSCRIBED
                      - INVALID_SSL
                      - UNSUBSCRIBED
  /on_subscribe:
    post:
      tags:
        - Subscriber
      description: 'Validates a subscriber. In this API the Registry generates a random string, encrypts it with the subscriber\''s encryption public key and sends it to the subscriber\''s callback URL. The subscriber then decrypts the string using it''s encryption private key and sends back the decypted value to the registry. If the decrypted value is the same as the sent value, the subscriber get''s added to the registry with a ```status = "SUBSCRIBED"```'
      parameters:
        - in: header
          name: Signature
          description: This contains the digital signature of the request body signed using the signing private key of the Registry
          schema:
            type: string
          required: true
      requestBody:
        description: Contains a subscriber challenge key to be decrypted by the subscriber
        content:
          application/json:
            schema:
              type: object
              properties:
                challenge:
                  type: string
                  description: A random string generated by the registry encrypted with the subscriber's encryption public key
              required:
                - challenge
      responses:
        '200':
          description: Registration status
          content:
            application/json:
              schema:
                type: object
                properties:
                  answer:
                    type: string
                    description: Decrypted value
                required:
                  - answer
  /lookup:
    post:
      tags:
        - Registry
      description: Look up subscriber(s) in a registry
      parameters:
        - in: header
          name: Signature
          description: This contains the digital signature of the request body signed using the signing private key of the Subscriber
          schema:
            type: string
          required: true
      requestBody:
        description: TODO
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriber_id:
                  type: string
                type:
                  enum:
                    - bap
                    - bpp
                    - bg
                domain:
                  $ref: '#/components/schemas/Domain'
                country:
                  $ref: '#/components/schemas/Country/properties/code'
                city:
                  $ref: '#/components/schemas/City/properties/code'
      responses:
        '200':
          description: List of subscribers with ```state = "SUBSCRIBED"```
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Subscriber'
components:
  schemas:
    City:
      description: Describes a city
      type: object
      properties:
        name:
          type: string
          description: Name of the city
        code:
          type: string
          description: City code
    
    Country:
      description: Describes a country.
      type: object
      properties:
        name:
          type: string
          description: Name of the country
        code:
          type: string
          description: Country code as per ISO 3166-1 and ISO 3166-2 format
    
    Domain:
      description: Describes the domain of an object
      type: string
      
    Subscriber:
      type: object
      properties:
        subscriber_id:
          type: string
        subscriber_url:
          type: string
          format: uri
        type:
          type: string
          enum:
            - BAP
            - BPP
            - BG
            - LREG
            - CREG
            - RREG
        domain:
          type: string
        city:
          type: string
        country:
          type: string
        signing_public_key:
          type: string
        encr_public_key:
          type: string
        valid_from:
          type: string
          format: date-time
        valid_until:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - INITIATED
            - UNDER_SUBSCRIPTION
            - SUBSCRIBED
            - EXPIRED
            - UNSUBSCRIBED
            - INVALID_SSL
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
  securitySchemes:
    DigitalSignatureAuth:
      type: http
      scheme: digest
security:
  - DigitalSignatureAuth: []