api.raml

#%RAML 1.0
---
title: Drivers
baseUri: https://desolate-basin-87139.herokuapp.com/api
description: |
  This is a go-kit powered micro-service, called Drivers.
  It serves REST-like API. This API provides only one resource, which is Driver.
  Example Driver {"id":1, "name":"JohnDoe", "license_number":"11-222-33"}.

/import:
  post:
    description: |
      Import a batch of drivers.
      For driver from a batch, would be applied upsert if there is an existing record with the same id in the database.
      
      Accepts json body with an array of drivers. Array size should be from 1 to 1000 elements

      Driver fields:
      * "id" is an uint64, must be greater thet 0
      * "name" is a string, length must be from 3 to 1000 UTF-8 symbols
      * "license_number" is a string, must match `^[0-9]{2}-[0-9]{3}-[0-9]{2}$`

    body:
      application/json:
        example: |
          [{
            "id": 1,
            "name": "John Doe",
            "license_number": "11-222-33"
          }]
    responses:
      200: ok
        body:
          application/json:
            example: {}
      400:
        description: validation error
        body:
          application/json:
            example: {"error":"status=400, error=invalid collection length; collection drivers should be from 1 to 1000 elements, but not 0"}
      409:
        description: insertion error
        body:
          application/json:
            example: {"error":"status=409, error=Key (license_number)=(11-222-33) already exists."}
      500:
        description: something yet unhandled or something really wrong
        body:
          application/json:
            example: {"error": "status=500 error=pq: Could not complete operation in a failed transaction"}
/driver/{id}:
  get:
    description: |
      Get a driver by id.

      "id" is a uint64, should be greater then 0.
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "id":1,
                "name": "JohnDoe",
                "license_number": "11-222-33"
              }
      400:
        description: validation error
        body:
          application/json:
            example: {"error":"status=400, error=invalid id; should be greater then 0"}
      404:
        description: search error
        body:
          application/json:
            example: {"error":"status=404, error=driver with id=3 is not found"}
      500:
        description: something yet unhandled or something really wrong
        body:
          application/json:
            example: {"error": "status=500 error=pq: Could not complete operation in a failed transaction"}