gistfile1.txt

info:
  version: 0.2.0
  title: Spring Labs Relay Provider
  description: APIs to interact with Relay Providers
  termsOfService: https://springlabs.com/terms/
  contact:
    name: Spring
    email: apiteam@springlabs.com
    url: https://springlabs.com
swagger: "2.0"
basePath: "/v1"
schemes:
- http
# TODO: setup HTTPS
# - https
consumes:
- application/json
produces:
- application/json
definitions:
  Error:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: integer
      message:
        type: string
  ChunkRequestEntry:
    properties:
      dataType:
        description: enum representing one of `metadata`, `salt`, or `data`
        type: integer
      data:
        type: string
        description: data that the algorithm will save
  ChunkResponseEntry:
    required:
      - algorithm
      - commitment
      - data
      - dataType
    properties:
      algorithm:
        description: the algorithm used to encrypt data; eg, SSS with n of m
        type: string
      commitment:
        description: the commitment being looked up
        type: string
      data:
        type: string
        description: data that the algorithm will save
      dataType:
        description: enum representing one of `metadata`, `salt`, or `data`
        type: integer
  ChunkCreateRequestData:
    type: object
    required:
      - algorithm
      - chunks
    properties:
      algorithm:
        type: string
        description: the algorithm used to encrypt data; eg, SSS with n of m
      chunks:
        description: chunks to store in database
        type: array
        items:
          type: object
          $ref: "#/definitions/ChunkRequestEntry"
  ChunkResponse:
    type: object
    required:
      - code
      - items
    properties:
      code:
        type: integer
      items:
        description: individual chunks saved for the attestation
        type: array
        items:
          type: object
          $ref: "#/definitions/ChunkResponseEntry"
  ProvisionKeyData:
    type: object
    required:
      - commitment
      - key
      - dataTypes
    properties:
      key:
        description: key to be provisioned for GET /chunks
        type: string
      commitment:
        description: the commitment being provisioned for
        type: string
      dataTypes:
        description: an array of data types being provisioned for
        type: array
        items:
          description: enum representing one of `metadata`, `salt`, or `data`
          type: integer
  ProvisionedKey:
    required:
      - commitment
      - dataType
      - key
    properties:
      key:
        description: key that was provisioned for chunk
        type: string
      commitment:
        description: the commitment of the chunk
        type: string
      dataType:
        description: enum representing one of `metadata`, `salt`, or `data`
        type: integer
  ProvisionKeyResponse:
    type: object
    required:
      - code
      - items
    properties:
      code:
        type: integer
      items:
        description: keys that were provisioned
        type: array
        items:
          type: object
          $ref: "#/definitions/ProvisionedKey"
paths:
  # TODO: signatures in header
  /chunks/{commitment}:
    put:
      operationId: app.controllers.chunks.put
      summary: save secret chunks of attestations
      description: An API that stores chunked secret data serviced by the data furnisher.
      parameters:
        - in: path
          name: commitment
          required: true
          type: string
          description: the commitment to use for lookup
        - in: body
          name: body
          schema:
            $ref: "#/definitions/ChunkCreateRequestData"
      responses:
        "200":
          description: Chunk properly created in relay provider database
          schema:
            $ref: "#/definitions/ChunkResponse"
        default:
          description: Error Payload
          schema:
            $ref: "#/definitions/Error"
    get:
      operationId: app.controllers.chunks.get
      summary: fetch chunk
      description: An API that returns secretly saved data
      parameters:
        - in: path
          name: commitment
          required: true
          type: string
          description: the commitment of the chunks being searched for
        - in: query
          name: key
          type: string
          description: key provisioned by Spring Node to read the chunk
        - in: query
          name: dataTypes
          required: true
          type: string
          description: the data types being searched for
      responses:
        "200":
          description: Chunk properly fetched
          schema:
            $ref: "#/definitions/ChunkResponse"
        default:
          description: Error Payload
          schema:
            $ref: "#/definitions/Error"
  /keys:
    put:
      operationId: app.controllers.keys.put
      summary: provision read key for data
      description: Returns a key allowing the relayer to read a specific chunk.  Can only be called by the Spring Node.
      parameters:
        - in: body
          name: body
          schema:
            $ref: "#/definitions/ProvisionKeyData"
      responses:
        "200":
          description: Key properly provisioned
          schema:
            $ref: "#/definitions/ProvisionKeyResponse"
        default:
          description: Error Payload
          schema:
            $ref: "#/definitions/Error"