Example mock DGC service API specification

api.yaml

swagger: '2.0'
info:
  version: 0.0.1
  title: DGC API for IO integration
host: example.com
schemes:
  - https
paths:
  # arbitrary path, let's find a proper one togheter
  /certificate:
    post:
      operationId: getCertificate
      summary: Retrieve a certificate for a given Citizen
      description: |-
        Given a Citizen's fiscal code and an OTP (the auth code previously sent via IO Message), a Certificate is returned with ID, encoded QR-code, expiration date and a markdown text with all meaningful information to be shown to Citizens.
      parameters:
        - name: accessData
          in: body
          schema:
            type: object
            properties:
              fiscal_code:
                type: string
                description: HASHED string representing the fiscal code which identifies the Citizen requesting the Certificate
              auth_code:
                type: string
                description: OTP previously sent to the Citizen
            required:
              - fiscal_code
              - auth_code
      responses:
        '200':
          description: |-
            A Certificate exists and it's found for the given access data. It is retrieved regardless of it's expired or its current status
          schema:
            type: object
            properties:
              qr_code:
                $ref: "#/definitions/QRCode"
            required:
              - qr_code
        '400':
          description: Payload has bad format
        '403':
          description: Access data provided are invalid or no Certificate has been emitted for the given Citizen
        '500':
          description: Generic server error

  /subscription:
    post:
      operationId: notifiySubscription
      summary: Notify DGC service a new Citizen subscried to IO and it's now willing to receive her/his Certificate messages
      description: |-
        When a Citizen joins IO and therefore is willing to receive message from DGC, this endpoint is solicitated. DGC will then send messages with data to access Citizen's Certificate, if any.
        DGC always accepts notifications regardless Citizen exists or it has Certificate yet
      parameters:
        - name: citizenId
          in: body
          schema:
            type: object
            properties:
              fiscal_code:
                type: string
                description: HASHED string representing the fiscal code which identifies the Citizen requesting the Certificate
            required:
              - fiscal_code
      responses:
        '202':
          description: The notification has been recorded
        '400':
          description: Payload has bad format
        '410':
          description: Certificate is expired
          schema:
            type: object
            properties:              
              id:
                description: Unique identifier of the Certificate
                type: string
            required:
              - id
        '500':
          description: Generic server error
definitions:
  QRCode:
    description: A qr code imamge encoded into a base64 string
    type: object
    properties:
      mime_type:
        description: the formate the image has been encoded in
        type: string
        enum:
          - "image/png"
          - "image/svg"
      content:
        description: a base64 string representing the image to be shown
        type: string
    required:
      - mime_type
      - content
    example:
      mime_type: "image/png"
      content: "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyMyAyMyI+PHBhdGggZmlsbD0iYmxhY2siIGQ9Ik0xIDFoN3Y3aC03ek05IDFoMXYxaC0xek0xMSAxaDJ2MWgtMXYxaC0ydi0xaDF6TTE1IDFoN3Y3aC03ek0yIDJ2NWg1di01ek0xNiAydjVoNXYtNXpNMyAzaDN2M2gtM3pNOSAzaDF2MWgtMXpNMTIgM2gxdjJoMXY0aC0xdi0yaC0xdjNoLTF2MWgxdi0xaDF2MWgxdjFoLTF2MWgydi0xaDF2MmgtNHYtMmgtMXYxaC0xdi0yaC0xdi0xaDF2LTFoMXYtMmgtMXYxaC0xdi0yaDF2LTJoMnpNMTcgM2gzdjNoLTN6TTEgOWgxdjFoLTF6TTMgOWgxdjFoLTF6TTcgOWgydjFoLTJ6TTE2IDloMXYxaC0xek0xOSA5aDF2MWgtMXpNMjEgOWgxdjJoLTJ2LTFoMXpNNCAxMGgydjFoLTF2MWgtMXpNMTQgMTBoMnYxaC0yek0xIDExaDJ2MWgtMXYxaDF2LTFoMXYxaDF2LTFoMXYtMWgzdjFoLTJ2MWgtMXYxaC01ek0xNyAxMWgxdjFoMXYxaDF2MmgtMXYtMWgtMXYtMWgtMXpNMTkgMTFoMXYxaC0xek0yMCAxMmgydjZoLTF2LTJoLTF2LTFoMXYtMmgtMXpNNyAxM2gxdjFoLTF6TTkgMTNoMXYzaC0xek0xNiAxNGgydjFoLTF2MWgtM3YtMWgyek0xIDE1aDd2N2gtN3pNMTEgMTVoMXYxaC0xek0xOCAxNWgxdjFoLTF6TTIgMTZ2NWg1di01ek0xMyAxNmgxdjFoLTF6TTE5IDE2aDF2MWgtMXpNMyAxN2gzdjNoLTN6TTExIDE3aDF2MWgtMXpNMTQgMTdoNXYxaC0xdjNoLTF2LTFoLTF2LTFoLTF2MWgxdjJoLTR2LTFoLTJ2LTFoMXYtMWgxdi0xaDF2MWgxek0xMCAxOGgxdjFoLTF6TTE5IDE4aDF2MWgtMXpNOSAxOWgxdjFoLTF6TTIwIDE5aDJ2M2gtM3YtMWgydi0xaC0xek0xMyAyMHYxaDF2LTF6TTkgMjFoMXYxaC0xeiIvPjwvc3ZnPg=="
    
consumes:
  - application/json
produces:
  - application/json