swagger: '2.0'
info:
  title: Swarm Global Store API
  version: 0.1.0
tags:
  - name: Has Key
    description: Checks if a Key is stored on a Node
  - name: Keys
    description: Lists Keys
  - name: Nodes
    description: Lists Node addresses

paths:
  '/api/has-key/{node}/{key}':
    get:
      tags:
        - Has Key
      summary: Checks if a Key is stored on a Node
      operationId: hasKey
      produces:
        - application/json

      parameters:
        - name: node
          in: path
          required: true
          type: string
          format: hex-endoded
          description: Node address.

        - name: key
          in: path
          required: true
          type: string
          format: hex-endoded
          description: Key.

      responses:
        '200':
          description: Key is stored on Node
          schema:
            $ref: '#/definitions/Status'
        '404':
          description: Key is not stored on Node
          schema:
            $ref: '#/definitions/Status'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Status'

  '/api/keys':
    get:
      tags:
        - Keys
      summary: Lists Keys
      operationId: keys
      produces:
        - application/json

      parameters:
        - name: start
          in: query
          required: false
          type: string
          format: hex-encoded Key
          description: A Key as the starting point for the returned list. It is usually a value from the returned "next" field in the Keys repsonse.

        - name: limit
          in: query
          required: false
          type: integer
          default: 100
          minimum: 1
          maximum: 1000
          description: Limits the number of Keys returned in on response.

        - name: node
          in: query
          required: false
          type: string
          format: hex-encoded Node address
          description: If this parameter is provided, only Keys that are stored on this Node be returned in the response. If not, all known Keys will be returned.

      responses:
        '200':
          description: List of Keys
          schema:
            $ref: '#/definitions/Keys'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Status'

  '/api/nodes':
    get:
      tags:
        - Nodes
      summary: Lists Node addresses
      operationId: nodes
      produces:
        - application/json

      parameters:
        - name: start
          in: query
          required: false
          type: string
          format: hex-encoded Node address
          description: A Node address as the starting point for the returned list. It is usually a value from the returned "next" field in the Nodes repsonse.

        - name: limit
          in: query
          required: false
          type: integer
          default: 100
          minimum: 1
          maximum: 1000
          description: Limits the number of Node addresses returned in on response.

        - name: key
          in: query
          required: false
          type: string
          format: hex-encoded Key
          description: If this parameter is provided, only addresses of Nodes that store this Key will be returned in the response. If not, all known Node addresses will be returned.
    
      responses:
        '200':
          description: List of Node addresses
          schema:
            $ref: '#/definitions/Nodes'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Status'

definitions:

  Status:
    type: object
    properties:
      message:
        type: string
        description: HTTP Status Code name.
      code:
        type: integer
        description: HTTP Status Code.

  Keys:
    type: object
    properties:
      keys:
        type: array
        description: A list of Keys.
        items:
          type: string
          format: hex-encoded Key
      next:
        type: string
        format: hex-encoded Key
        description: If present, the next Key in listing. Can be passed as "start" query parameter to continue the listing. If not present, the end of the listing is reached.

  Nodes:
    type: object
    properties:
      nodes:
        type: array
        description: A list of Node addresses.
        items:
          type: string
          format: hex-encoded Node address
      next:
        type: string
        format: hex-encoded Node address
        description: If present, the next Node address in listing. Can be passed as "start" query parameter to continue the listing. If not present, the end of the listing is reached.