openapi.yaml

openapi: 3.0.0

info:
  title: Clkhash REST API
  version: 0.1.0
  x-logo:
    url: http://clkhash.readthedocs.io/en/latest/_static/logo.svg
  description: |
    A simple REST wrapper around [clkhash](https://github.com/data61/clkhash).

    This API lets you upload personally identifying information (PII) for hashing, and to retrieve the hashes.
    It does not provide the option to download the raw PII.

  contact:
    name: 'Confidential Computing, Data61 | CSIRO'
    email: confidential-computing@csiro.au
    url: https://github.com/data61/anonlink-encoding-service

servers:
- url: http://localhost:8000
  description: Local deployment

tags:
  - name: projects
    description: A project is a namespace associated with a schema and keys. All uploaded
      data must belong to a project. Before uploading any private data, a
      project with some ID assigned by the user must be created.
  - name: clks
    description: These methods operate on the data and the hashes, permitting us to upload
      private information, view progress of the hashing, retrieve the clks, and
      delete information.
paths:
  /projects/:
    get:
      summary: List existing linkage projects.
      description: Lists the IDs of existing linkage projects. Every linkage project has a
        unique ID. To retrieve more information about a project, use
        `/projects/{project_id}`.
      tags:
        - projects
      operationId: clkhash_service.get_projects
      responses:
        "200":
          description: List of linkage projects. Every item in the list is a project ID.
          content:
            application/json:
              examples:
                response:
                  value:
                    projects:
                      - example-project
                      - another-project
    post:
      summary: Add a new linkage project.
      description: Create a new project. This permits us to save the schema and keys in the
        server and bind all related private data to the same ID. The keys
        uploaded here cannot be retrieved from the server.
      tags:
        - projects
      operationId: clkhash_service.post_project
      parameters:
        - name: project_id
          in: query
          description: The ID of the linkage project. Must be unique.
          required: true
          schema:
            type: string
        - name: secret_key
          description: A base64 encoding string of the shared secret. These need to be
            URL-encoded since base64 is not URL-safe by default.
          in: query
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              example:
                version: 1
                clkConfig:
                  l: 1024
                  k: 20
                  hash:
                    type: doubleHash
                  kdf:
                    type: HKDF
                    hash: SHA256
                    salt: SCbL2zHNnmsckfzchsNkZY9XoHk96P/G5nUBrM7ybymlEFsMV6PAeDZCNp3rfNUPCtLDMOGQHG4pCQpfhiHCyA==
                    info: c2NoZW1hX2V4YW1wbGU=
                    keySize: 64
                features:
                  - identifier: NAME freetext
                    format:
                      type: string
                      encoding: utf-8
                      case: mixed
                      minLength: 3
                    hashing:
                      ngram: 2
                      weight: 0.5
                  - identifier: DOB YYYY/MM/DD
                    format:
                      type: string
                      encoding: ascii
                      description: Numbers separated by slashes, in the year, month, day
                        order
                      pattern: \d\d\d\d/\d\d/\d\d
                    hashing:
                      ngram: 1
                      positional: true
                  - identifier: GENDER M or F
                    format:
                      type: enum
                      values:
                        - M
                        - F
                    hashing:
                      ngram: 1
                      weight: 2
        description: Controls the way the hashing is performed and the format of the
          fields. This must be consistent between the parties whose data is
          being linked. See documentation at
          http://clkhash.readthedocs.io/en/latest/schema.html.
        required: true
      responses:
        "201":
          description: Successfully created project. The response body is empty.
        "409":
          description: Project with this ID already exists. The `"errMsg"` key contains the
            error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Project 'example_project' already exists.
        "422":
          description: The parameters are not valid. The `"errMsg"` key contains the error
            message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: The schema does not conform to the master schema.
  "/projects/{project_id}":
    parameters:
      - $ref: "#/components/parameters/project_id"
    get:
      summary: Retrieve properties of the specified project.
      description: Retrieves the public properties (currently the schema) of the specified
        object.
      tags:
        - projects
      operationId: clkhash_service.get_project
      responses:
        "200":
          description: Properties of specified object.
          content:
            application/json:
              examples:
                response:
                  value:
                    projectId: example-project
                    schema:
                      version: 1
                      clkConfig:
                        l: 1024
                        k: 20
                        hash:
                          type: doubleHash
                        kdf:
                          type: HKDF
                          hash: SHA256
                          salt: SCbL2zHNnmsckfzchsNkZY9XoHk96P/G5nUBrM7ybymlEFsMV6PAeDZCNp3rfNUPCtLDMOGQHG4pCQpfhiHCyA==
                          info: c2NoZW1hX2V4YW1wbGU=
                          keySize: 64
                      features:
                        - identifier: NAME freetext
                          format:
                            type: string
                            encoding: utf-8
                            case: mixed
                            minLength: 3
                          hashing:
                            ngram: 2
                            weight: 0.5
                        - identifier: DOB YYYY/MM/DD
                          format:
                            type: string
                            encoding: ascii
                            description: Numbers separated by slashes, in the year, month,
                              day order
                            pattern: \d\d\d\d/\d\d/\d\d
                          hashing:
                            ngram: 1
                            positional: true
                        - identifier:
                            format:
                              type: enum
                              values:
                                - M
                                - F
                            hashing:
                              ngram: 1
                              weight: 2
        "404":
          description: No such project. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Project 'example-project' does not exist.
    delete:
      summary: Delete the linkage project.
      description: Deletes the linkage project, along with its schema and keys. This
        deletes any computed all hashes. If some hashing was still pending,
        those jobs are aborted.
      tags:
        - projects
      operationId: clkhash_service.delete_project
      responses:
        "204":
          description: Successfully deleted. The response body is empty.
        "404":
          description: No such project. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Project 'example-project' does not exist.
  "/projects/{project_id}/pii/":
    parameters:
      - $ref: "#/components/parameters/project_id"
    post:
      summary: Post PII to hash.
      description: Save private information to the server and schedule the hashing. The
        private information cannot be retrieved from the API in its original
        form; only the hashes are made available. It is deleted as soon as the
        hash is produced.
      tags:
        - clks
      operationId: clkhash_service.post_pii
      parameters:
        - name: header
          description: "Default 'true': the CSV input has a header row and we wish to
            validate the column names against the schema. Set to 'ignore' to
            skip the header row. Set to 'false' if the table does not have a
            header row."
          in: query
          required: false
          schema:
            type: string
            enum:
              - "false"
              - ignore
              - "true"
            default: "true"
        - name: validate
          description: If `true`, validate the PII before hashing.
          in: query
          required: false
          schema:
            type: boolean
            default: true
      requestBody:
        content:
          text/csv:
            schema:
              type: string
              example: |
                NAME freetext,DOB YYYY/MM/DD,GENDER M or F
                Jane Doe,1968/05/19,F
                Peter Griffin,1998/12/20,M
        required: true
      responses:
        "202":
          description: Successfully sent for hashing. Returns the IDs of the post rows as a
            consecutive range. The range-end is inclusive.
          content:
            application/json:
              examples:
                response:
                  value:
                    dataIds:
                      rangeStart: 0
                      rangeEnd: 1
        "404":
          description: No such project. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Project 'example-project' does not exist.
        "422":
          description: Invalid data. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Invalid entry on line 21.
  "/projects/{project_id}/clks/status":
    parameters:
      - $ref: "#/components/parameters/project_id"
    get:
      summary: Get status of all clks.
      description: Returns the status of each clk.
      tags:
        - clks
      operationId: clkhash_service.get_clks_status
      responses:
        "200":
          description: The status of each clk, by index. For convenience, adjacent clks
            with the same status are grouped together. The list is empty if
            there are not clks. Each list element contains `rangeStart`, the
            first index included; `rangeEnd`, the last index included; and a
            `status` string. Possible statuses are `queued` (awaiting
            processing), `in-progress` (being processed now), `done` (ready for
            retrieval), `invalid-data` (data did not pass validation against the
            schema), and `error` (internal error).
          content:
            application/json:
              examples:
                response:
                  value:
                    clksStatus:
                      - rangeStart: 0
                        rangeEnd: 16003
                        status: done
                      - rangeStart: 16002
                        rangeEnd: 100003
                        status: queued
        "404":
          description: No such project. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Project 'example-project' does not exist.
  "/projects/{project_id}/clks/":
    parameters:
      - $ref: "#/components/parameters/project_id"
      - name: index_range_start
        in: query
        description: The index of the first clk to operate on.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: index_range_end
        in: query
        description: The index of the last clk to operate on, plus one.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: status
        in: query
        description: Comma-separated list. Permits filtering on status. Only clks with
          their status listed here will be returned. Permitted statuses are
          `queued`, `in-progress`, `done`, `invalid-data`, and `error`.
        required: false
        schema:
          type: string
          minLength: 1
    get:
      summary: Retrieve the clks, if available.
      description: Retrieve the index, status, and hash of each clk.
      tags:
        - clks
      parameters:
        - name: page_limit
          in: query
          description: The number of items per page. Leave this out to disable pagination.
          required: false
          schema:
            type: integer
            minimum: 1
        - name: cursor
          in: query
          description: The cursor used to iterate through pages. This is returned by the
            previous response. Leave out to retrieve the first page.
          required: false
          schema:
            type: string
            minLength: 1
      operationId: clkhash_service.get_clks
      responses:
        "200":
          description: The clks are returned along with their status. The hash is `null`
            where it has not been computed. The list is empty if there are no
            clks with IDs in the specified range. A `responseMetadata` object is
            returned. It contains a `nextCursor` string which must be passed in
            the next request to retrieve the next page; it is URL-safe, so no
            URL encoding is required. The `nextCursor` is `null` if no next page
            is available.
          content:
            application/json:
              examples:
                response:
                  value:
                    count: 2
                    clks:
                      - errMsg: Column `DOB YYYY/MM/DD` did not pass validation.
                        hash: null
                        index: 0
                        status: invalid-data
                      - errMsg: null
                        hash: 2wRKwCio1SQDeAAEowBECdwNGkAJgChviDATAHTDRCgQECHqxiEARgl+iLQADIspmCB7gcFUgKGIwvCMBAirULh5kkDaiTlAJowckX8A0BEgk8MgkABIF2EmByhJK6AiMwCGjlGYIlCCwiQAICED4QEgBAMsIBiAMBDkGyCSQAI=
                        index: 1
                        status: done
                    responseMetadata:
                      nextCursor: LTE0Nzg0OTA3ODA5NDE2MDA0MTk
        "404":
          description: No such project. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Project 'example-project' does not exist.
        "422":
          description: Invalid parameters. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: The provided cursor is invalid.
    delete:
      summary: If finished hashing, delete the clks. Otherwise, abandon hashing and
        delete the PII.
      description: Deletes specified entry from the server, including any hashes and
        private data. If the hashing has not occured, cancels the scheduled job.
        If there are no clks within the specified range, do nothing.
      tags:
        - clks
      operationId: clkhash_service.delete_clks
      responses:
        "204":
          description: Successfully deleted. Number of deleted items specified in the
            payload. If there were no items within the range, this number will
            be 0.
          content:
            application/json:
              examples:
                response:
                  value:
                    count: 2
        "404":
          description: No such project. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: Project 'example-project' does not exist.
        "422":
          description: Invalid parameters. The `"errMsg"` key contains the error message.
          content:
            application/json:
              examples:
                response:
                  value:
                    errMsg: "Error in argument `status`: 'obviously-wrong-status' is
                      not a valid status."
components:
  parameters:
    project_id:
      name: project_id
      in: path
      description: The ID of the linkage project. Must be unique.
      required: true
      schema:
        type: string