api-docs.json

{
   "openapi":"3.0.1",
   "info":{
      "title":"cwa-dcc-server",
      "license":{
         "name":"Apache 2.0",
         "url":"http://www.apache.org/licenses/LICENSE-2.0"
      },
      "version":"1.0.0-SNAPSHOT"
   },
   "servers":[
      {
         "url":"http://localhost:8080",
         "description":"Generated server url"
      }
   ],
   "paths":{
      "/version/v1/dcc":{
         "post":{
            "tags":[
               "external"
            ],
            "summary":"COVID-19 Test Result DCC Components",
            "description":"Gets the components to build a Digital Covid Certificate with the result of COVID-19 Test.",
            "operationId":"claimDcc",
            "parameters":[
               {
                  "name":"cwa-fake",
                  "in":"header",
                  "description":"Flag whether this request should be handled as fake request",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "requestBody":{
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/RegistrationToken"
                     }
                  }
               },
               "required":true
            },
            "responses":{
               "415":{
                  "description":"Unsupported Media Type"
               },
               "405":{
                  "description":"Method Not Allowed"
               },
               "400":{
                  "description":"Bad Request. (Invalid RegistrationToken format)"
               },
               "500":{
                  "description":"Internal Server Error",
                  "content":{
                     "application/json":{
                        "schema":{
                           "$ref":"#/components/schemas/DccUnexpectedError"
                        }
                     }
                  }
               },
               "200":{
                  "description":"DCC Components retrieved.",
                  "content":{
                     "*/*":{
                        "schema":{
                           "$ref":"#/components/schemas/DccResponse"
                        }
                     }
                  }
               },
               "202":{
                  "description":"DCC is pending.",
                  "content":{
                     "*/*":{
                        "schema":{
                           "type":"object"
                        }
                     }
                  }
               },
               "404":{
                  "description":"Registration Token does not exist/ is not registered at DCC-Server.",
                  "content":{
                     "*/*":{
                        "schema":{
                           "type":"object"
                        }
                     }
                  }
               },
               "410":{
                  "description":"DCC already cleaned up.",
                  "content":{
                     "*/*":{
                        "schema":{
                           "type":"object"
                        }
                     }
                  }
               }
            }
         }
      },
      "/version/v1/test/{testId}/dcc":{
         "post":{
            "tags":[
               "internal"
            ],
            "summary":"Upload a DCC for a test.",
            "description":"Endpoint to upload components to build the DCC.",
            "operationId":"uploadDcc",
            "parameters":[
               {
                  "name":"testId",
                  "in":"path",
                  "description":"ID of the test (hashed GUID).",
                  "required":true,
                  "schema":{
                     "pattern":"^[XxA-Fa-f0-9]([A-Fa-f0-9]{63})$",
                     "type":"string"
                  }
               },
               {
                  "name":"X-CWA-PARTNER-ID",
                  "in":"header",
                  "description":"PartnerID. This needs only to be set if DCC-Server is contacted without DCC-Proxy in between.",
                  "required":true,
                  "schema":{
                     "pattern":"^[A-Za-z0-9]{1,64}$",
                     "type":"string"
                  }
               }
            ],
            "requestBody":{
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/DccUploadRequest"
                     }
                  }
               },
               "required":true
            },
            "responses":{
               "415":{
                  "description":"Unsupported Media Type"
               },
               "405":{
                  "description":"Method Not Allowed"
               },
               "400":{
                  "description":"Invalid Data format"
               },
               "500":{
                  "description":"Internal Server Error"
               },
               "201":{
                  "description":"DCC created",
                  "content":{
                     "application/json":{
                        "schema":{
                           "$ref":"#/components/schemas/DccUploadResponse"
                        }
                     }
                  }
               },
               "403":{
                  "description":"LabId is not or cannot be assigned to Partner.",
                  "content":{
                     "*/*":{
                        "schema":{
                           "type":"object"
                        }
                     }
                  }
               },
               "404":{
                  "description":"Test does not exists",
                  "content":{
                     "*/*":{
                        "schema":{
                           "type":"object"
                        }
                     }
                  }
               },
               "409":{
                  "description":"DCC already exists",
                  "content":{
                     "*/*":{
                        "schema":{
                           "type":"object"
                        }
                     }
                  }
               }
            }
         }
      },
      "/version/v1/publicKey/search/{labId}":{
         "get":{
            "tags":[
               "internal"
            ],
            "summary":"Search Public Keys and Test Ids for given LabId",
            "description":"Endpoint to search and download all PublicKeys which are assigned to a testId and the given lab Id.",
            "operationId":"searchPublicKeys",
            "parameters":[
               {
                  "name":"X-CWA-PARTNER-ID",
                  "in":"header",
                  "description":"PartnerID. This needs only to be set if DCC-Server is contacted without DCC-Proxy in between.",
                  "required":true,
                  "schema":{
                     "pattern":"^[A-Za-z0-9]{1,64}$",
                     "type":"string"
                  }
               },
               {
                  "name":"labId",
                  "in":"path",
                  "description":"ID of the laboratory to search for.",
                  "required":true,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "responses":{
               "415":{
                  "description":"Unsupported Media Type"
               },
               "405":{
                  "description":"Method Not Allowed"
               },
               "400":{
                  "description":"Bad Request"
               },
               "500":{
                  "description":"Internal Server Error"
               },
               "200":{
                  "description":"Public Key list returned.",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"array",
                           "items":{
                              "$ref":"#/components/schemas/LabPublicKeyInfo"
                           }
                        }
                     }
                  }
               },
               "403":{
                  "description":"LabId is not or cannot be assigned to Partner.",
                  "content":{
                     "*/*":{
                        "schema":{
                           "type":"array",
                           "items":{
                              "$ref":"#/components/schemas/LabPublicKeyInfo"
                           }
                        }
                     }
                  }
               }
            }
         }
      },
      "/version/v1/labId":{
         "post":{
            "tags":[
               "internal"
            ],
            "summary":"Claims a new LabId for partner.",
            "description":"Checks if the given LabId is not in use and creates a claim to associate it with the partner.",
            "operationId":"claimLabId",
            "parameters":[
               {
                  "name":"X-CWA-PARTNER-ID",
                  "in":"header",
                  "description":"PartnerID. This needs only to be set if DCC-Server is contacted without DCC-Proxy in between.",
                  "required":true,
                  "schema":{
                     "pattern":"^[A-Za-z0-9]{1,64}$",
                     "type":"string"
                  }
               }
            ],
            "requestBody":{
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/LabIdClaimRequest"
                     }
                  }
               },
               "required":true
            },
            "responses":{
               "415":{
                  "description":"Unsupported Media Type"
               },
               "405":{
                  "description":"Method Not Allowed"
               },
               "400":{
                  "description":"Invalid LabId format"
               },
               "500":{
                  "description":"Internal Server Error"
               },
               "204":{
                  "description":"LabId is claimed to you.",
                  "headers":{
                     "X-CWA-REMAINING-LAB-ID":{
                        "description":"Amount of remaining LabIds which can be claimed by partner",
                        "style":"simple",
                        "schema":{
                           "type":"string"
                        }
                     }
                  }
               },
               "403":{
                  "description":"LabId Quota is exceeded by partner."
               },
               "409":{
                  "description":"LabId is already used by another partner."
               }
            }
         }
      },
      "/version/v1/publicKey":{
         "post":{
            "tags":[
               "external"
            ],
            "summary":"Upload a Public Key",
            "description":"Uploads a Public Key to a Registration Token from Verification Server to generate Digital Covid Certificate data.",
            "operationId":"uploadPublicKey",
            "parameters":[
               {
                  "name":"cwa-fake",
                  "in":"header",
                  "description":"Flag whether this request should be handled as fake request",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "requestBody":{
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/UploadPublicKeyRequest"
                     }
                  }
               },
               "required":true
            },
            "responses":{
               "415":{
                  "description":"Unsupported Media Type"
               },
               "405":{
                  "description":"Method Not Allowed"
               },
               "400":{
                  "description":"Bad Request. (e.g. Wrong Format of RegistrationToken or PublicKey)."
               },
               "500":{
                  "description":"Internal Server Error"
               },
               "201":{
                  "description":"Public Key uploaded and associated."
               },
               "403":{
                  "description":"RegistrationToken is not allowed to issue a DCC (e.g. Token is issued for TeleTan)."
               },
               "404":{
                  "description":"RegistrationToken does not exists."
               },
               "409":{
                  "description":"RegistrationToken is already assigned with a PublicKey."
               }
            }
         }
      }
   },
   "components":{
      "schemas":{
         "RegistrationToken":{
            "required":[
               "registrationToken"
            ],
            "type":"object",
            "properties":{
               "registrationToken":{
                  "pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$",
                  "type":"string",
                  "description":"registrationToken from Verification Server"
               }
            },
            "description":"The registration token model."
         },
         "DccResponse":{
            "type":"object",
            "properties":{
               "dek":{
                  "type":"string",
                  "description":"Data Encryption Key (Encrypted AES-256 Key, encrypted with uploaders public key"
               },
               "dcc":{
                  "type":"string",
                  "description":"Base64 encoded DCC COSE Object. Payload is encrypted with data encryption key."
               }
            },
            "description":"The Dcc Response Model."
         },
         "DccUnexpectedError":{
            "type":"object",
            "properties":{
               "reason":{
                  "type":"string",
                  "description":"Reason of failure.",
                  "enum":[
                     "SIGNING_CLIENT_ERROR",
                     "SIGNING_SERVER_ERROR",
                     "LAB_INVALID_RESPONSE",
                     "INTERNAL"
                  ]
               }
            },
            "description":"The DCC Unexpected Error model. Holds the error which has occured during creation of DCC."
         },
         "DccUploadRequest":{
            "required":[
               "dataEncryptionKey",
               "encryptedDcc"
            ],
            "type":"object",
            "properties":{
               "dccHash":{
                  "pattern":"^[A-Fa-f0-9]{64}$",
                  "type":"string",
                  "description":"SHA256 Hash of plain DCC payload."
               },
               "encryptedDcc":{
                  "maxLength":1000,
                  "minLength":0,
                  "pattern":"^[A-Za-z0-9+/=]*$",
                  "type":"string",
                  "description":"Base64 encoded encrypted DCC payload."
               },
               "dataEncryptionKey":{
                  "maxLength":600,
                  "minLength":0,
                  "pattern":"^[A-Za-z0-9+/=]*$",
                  "type":"string",
                  "description":"Base64 encoded with PublicKey encrypted Data Encryption Key for encrypted DCC."
               }
            },
            "description":"Request payload to upload a DCC from laboratory."
         },
         "DccUploadResponse":{
            "type":"object",
            "properties":{
               "partialDcc":{
                  "type":"string",
                  "description":"Base64 encoded DCC Structure without the payload. (COSE/CBOR, Payload needs to be replaced by laboratory)"
               }
            },
            "description":"Response for uploaded DCC data."
         },
         "LabPublicKeyInfo":{
            "type":"object",
            "properties":{
               "testId":{
                  "type":"string",
                  "description":"Hashed GUID of the test."
               },
               "dcci":{
                  "type":"string",
                  "description":"The DCCI of the to be created DCC."
               },
               "publicKey":{
                  "type":"string",
                  "description":"The PublicKey to encrypt the Data Encryption Key with.",
                  "format":"Base64 encoded X509 SubjectPublicKeyInformation Object (RSA or EC Key)"
               }
            },
            "description":"Information a lab receives when searching for PublicKeys"
         },
         "LabIdClaimRequest":{
            "type":"object",
            "properties":{
               "labId":{
                  "pattern":"^[A-Za-z0-9]{1,64}$",
                  "type":"string",
                  "description":"LabId to claim."
               }
            },
            "description":"Request payload to claim a LabId."
         },
         "UploadPublicKeyRequest":{
            "required":[
               "publicKey",
               "registrationToken"
            ],
            "type":"object",
            "properties":{
               "registrationToken":{
                  "pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}$",
                  "type":"string",
                  "description":"registrationToken from Verification Server"
               },
               "publicKey":{
                  "type":"string",
                  "description":"Base64 encoded public key in DER format to encrypt DCC payload components."
               },
               "responsePadding":{
                  "type":"string"
               }
            },
            "description":"Request payload to upload a Public Key."
         }
      }
   }
}