openapi: 3.0.0
info:
  title: Hashdate API
  version: 0.1.0
  description: Add and query hashes

servers:
  - url: https://api.hashdate.org

paths:
  /add/{hashes}:
    post:
      summary: Add one or more hashes to the database
      parameters:
        - name: hashes
          description: 256-bit hashes in unprefixed hex, comma-separated. Max of 156.
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Hash256List'
      responses:
        '201':
          description: Added
        '208':
          description: Already added
        '400':
          description: Bad or missing hash
        '414':
          description: Too long
        '5XX':
          description: Server error

  /query/{hash}:
    get:
      summary: Look up a hash in the database
      parameters:
        - name: hash
          description: 256-bit hash in hex
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Hash256'
      responses:
        '200':
          description: Found bundled hash
          content:
            application/json:    
              schema:
                $ref: '#/components/schemas/BundledHashRecord'
        '204':
          description: Found unbundled hash
        '404':
          description: Not found
        '5XX':
          description: Server error

  /bundle/{id}:
    get:
      summary: Fetch a bundle file from the database
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Not found
        '5XX':
          description: Server error

components:
  schemas:
    Hash256:
      type: string
      pattern: '^[0-9a-fA-F]{64}$'
    Hash256List:
      type: string
      pattern: '^[0-9a-fA-F]{64}(,\s*[0-9a-fA-F]{64})*,?\s*$'
    BundledHashRecord:
      type: object
      properties:
        id:
          type: integer
        date:
          type: string
        hash:
          $ref: '#/components/schemas/Hash256'
        block:
          type: integer
