openapi: 3.0.3
info:
  title: did:webvh Watcher OpenAPI Definition
  description: |-
    This is the did:webvh watcher API definition. As per the did:webvh specification, a did:webvh watcher referenced in a did:webvh DID Log MUST implement at least this API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about did:webvh and did:webvh Watchers
  url: https://didwebvh.info
servers: []
tags:
  - name: log
    description: did:webvh DID Log related operations
  - name: witness
    description: did:webvh Witness related operations
  - name: resource
    description: did:webvh DID Resource related operations
paths:
  /log:
    get:
      tags:
        - log
      summary: Return the latest DID Log file
      parameters:
        - $ref: '#/components/parameters/SCID'
      responses:
        '200':
          description: successful operation
          content:
            text/jsonl:
              schema:
                $ref: '#/components/schemas/LogFile'      
        '400':
          description: Invalid SCID value
        '404':
          description: Unknown SCID value
    post:
      tags:
        - log
      summary: Notify the did:webvh Watcher that DID has been updated
      parameters:
        - $ref: '#/components/parameters/DID'
      responses:
        '202':
          description: Request received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: Invalid input
        '422':
          description: Validation exception
  /log/delete:
    post:
      tags:
        - log
      summary: Request deletion of the cached did:webvh DID
      parameters:
        - $ref: '#/components/parameters/SCID'
      requestBody: 
        $ref: '#/components/requestBodies/VerifiablePresentation'
      responses:
        '202':
          description: Request received
        '400':
          description: Invalid SCID value
        '404':
          description: Unknown SCID value
  /witness:
    get:
      tags:
        - witness
      summary: Return the latest witness file for the DID with the given SCID
      parameters:
        - $ref: '#/components/parameters/SCID'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WitnessFile'      
        '400':
          description: Invalid SCID value
        '404':
          description: Unknown SCID value
  /resource:
    get:
      tags:
        - resource
      summary: Return resource
      parameters:
        - $ref: '#/components/parameters/SCID'
        - $ref: '#/components/parameters/resourcePath'
      responses:
        '200':
          description: successful operation   
        '400':
          description: Invalid SCID value
        '404':
          description: Unknown SCID value or resource not found
    post:
      tags:
        - resource
      summary: Notify a new resource is available
      parameters:
        - $ref: '#/components/parameters/SCID'
        - $ref: '#/components/parameters/resourcePath'
      requestBody: 
        $ref: '#/components/requestBodies/VerifiablePresentation'
      responses:
        '202':
          description: Request received
        '400':
          description: Invalid input
        '404':
          description: Unknown SCID value
        '422':
          description: Validation exception
  /resource/delete:
    post:
      tags:
        - resource
      summary: Request deletion of a cached resource
      parameters:
        - $ref: '#/components/parameters/SCID'
        - $ref: '#/components/parameters/resourcePath'
      requestBody: 
        $ref: '#/components/requestBodies/VerifiablePresentation'
      responses:
        '202':
          description: Request received
        '400':
          description: Invalid SCID value
        '404':
          description: Unknown SCID value or resource not found
components:
  schemas:
    EmptyResponse:
      type: object
    DataIntegrityProof:
      type: object
      properties:
        type: 
          type: string
          example: 'DataIntegrityProof'
        cryptosuite: 
          type: string
          example: 'eddsa-jcs-2022'
        verificationMethod:
          type: string
        proofValue:
          type: string
        proofPurpose:
          type: string
          example: 'assertionMethod'
    VerifiablePresentation:
      type: object
      properties:
        '@context': 
          type: array
          items:
              type: string
          example:
           - 'https://www.w3.org/ns/credentials/v2'
        type:
          type: string
          example: 'VerifiablePresentation'
        proof:
          type: object
          properties:
            type: 
              type: string
              example: 'DataIntegrityProof'
            cryptosuite: 
              type: string
              example: 'eddsa-jcs-2022'
            verificationMethod:
              type: string
              example: 'did:key:{updateKey}'
            proofPurpose:
              type: string
              example: 'authentication'
            proofValue:
              type: string
            challenge:
              type: string
              example: "{SCID}"
            domain:
              type: string
              example: 'https://watcher.example.com'
    WitnessFile:
      type: object
      properties:
        versionId:
          type: string
        proof:
          type: array
          items:
            $ref: '#/components/schemas/DataIntegrityProof'
    LogFile:
      type: string
      description: The DID log file contains a list of entries, one for each version of the DID. Each entry has (per the JSON Lines specification) all extra whitespace removed, a \n character appended, and the result added to the DID Log.
      example: |
          {"versionId":"","versionTime":"","parameters":{},"state":{},"proof":[]}
          {"versionId":"","versionTime":"","parameters":{},"state":{},"proof":[]}
          {"versionId":"","versionTime":"","parameters":{},"state":{},"proof":[]}
  parameters:
    SCID:
      name: scid
      in: query
      description: SCID
      required: true
      schema:
        type: string
    DID:
      name: did
      in: query
      description: DID
      required: true
      schema:
        type: string
    resourcePath:
      name: path
      in: query
      description: Resource Path, this value needs to be url encoded.
      required: true
      schema:
        type: string
  requestBodies:
    VerifiablePresentation:
      description: A DataIntegrityProof used for Authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerifiablePresentation'