swagger: "2.0"
info:
  title: Batcomputer API
  version: "1.0.0"
host: api.batcomputer.com
paths:
  /persons:
    get:
      summary: List Persons
      description: |
        Retrieves a list of all persons on file in the bat computer.
      responses:
        200:
          description: An array of Persons
          schema:
            type: array
            items:
              $ref: '#/definitions/Person'
  /evidence:
    get:
      summary: List Evidence
      description: |
        Retrieves a list of evidence ever found by world's greatest
        detective and his family.
      parameters:
        - name: marker
          in: query
          type: integer
          minimum: -1
          default: -1
          format: int64
          required: false
          description: |
            The id of the last seen evidence. It's used for pagination purpose
            by returning 'limit' number of evidence after this one.
        - name: limit
          in: query
          type: integer
          format: int32
          minimum: 1
          maximum: 1000
          default: 20
          required: false
          description: |
            The maximum number of evidence to be returned by the query.
      responses:
        200:
          description: An array of evidence.
          schema:
            type: array
            items:
              $ref: '#/definitions/Evidence'
    post:
      summary: Create an Evidence
      description: |
        Creates a new evidence record in database.
      parameters:
        - name: evidence
          in: body
          schema:
            $ref: '#/definitions/Evidence'
      responses:
        201:
          description: An evidence.
          schema:
            $ref: '#/definitions/Evidence'
  /evidence/{id}:
    get:
      summary: Show Requested Evidence
      description: |
        Queries and returns an evidence with a passed ID.
      parameters:
        - name: id
          in: path
          type: integer
          format: int64
          required: true
          description: |
            A unique evidence identifier to query.
        - name: If-None-Match
          in: header
          type: string
          description: |
            Executes a request only if passed ETag doesn't equal to current
            resource one (i.e. resource has been changed).
      responses:
        200:
          description: An evidence.
          schema:
            $ref: '#/definitions/Evidence'
          headers:
            ETag:
              description: |
                Entity tag is part of HTTP provided for web cache validation
                problem, but also used for optimistic concurrency control.
              type: string
        404:
          description: Evidence not found.
          schema:
            $ref: '#/definitions/Error'
definitions:
  Evidence:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: A unique evidence identifier.
      case:
        type: string
        description: A case when the evidence is found.
      data:
        type: string
        format: binary
        description: An evidence itself.
  Error:
    type: object
    properties:
      code:
        type: string
        description: A uniqe identifier of error.
      message:
        type: string
        description: A human readable error message.
  Person:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: Unique ID for a person
      name:
        type: string
        description: Name of a person
