async-race-api

Api for Rolling Scopes School task "Async Race".

Setup and Running

  • Use node 14.x or higher.
  • Clone this repo: $ git clone https://github.com/mikhama/async-race-api.git.
  • Go to downloaded folder: $ cd async-race-api.
  • Install dependencies: $ npm install.
  • Start server: $ npm start.
  • Now you can send requests to the address: http://127.0.0.1:3000.

Usage

Get Cars

Returns json data about cars in a garage.

  • URL

    /garage

  • Method:

    GET

  • Headers:

    None

  • URL Params

    None

  • Query Params

    Optional:

    _page=[integer]

    _limit=[integer]

    If _limit param is passed api returns a header X-Total-Count that countains total number of records.

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        [
          {
            "name": "Tesla",
            "color": "#e6e6fa",
            "id": 1
          }
        ]
      Headers:
        "X-Total-Count": "4"
      
  • Error Response:

    None

  • Notes:

    None

Get Car

Returns json data about specified car.

  • URL

    /garage/:id

  • Method:

    GET

  • Headers:

    None

  • URL Params

    Required:

    id=[integer]

  • Query Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        {
          "name": "Tesla",
          "color": "#e6e6fa",
          "id": 1
        }
  • Error Response:

    • Code: 404 NOT FOUND
      Content:
        {}
  • Notes:

    None

Create Car

Creates a new car in a garage.

  • URL

    /garage

  • Method:

    POST

  • Headers:

    'Content-Type': 'application/json'

  • URL Params

    None

  • Query Params

    None

  • Data Params

      {
        name: string,
        color: string
      }
  • Success Response:

    • Code: 201 CREATED
      Content:
        {
            "name": "New Red Car",
            "color": "#ff0000",
            "id": 10
        }
  • Error Response:

    None

  • Notes:

    None

Delete Car

Delete specified car from a garage

  • URL

    /garage/:id

  • Method:

    DELETE

  • Headers:

    None

  • URL Params

    Required:

    id=[integer]

  • Query Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        {}
  • Error Response:

    • Code: 404 NOT FOUND
      Content:
        {}
  • Notes:

    None

Update Car

Updates attributes of specified car.

  • URL

    /garage/:id

  • Method:

    PUT

  • Headers:

    'Content-Type': 'application/json'

  • URL Params

    Required:

    id=[integer]

  • Query Params

    None

  • Data Params

      {
        name: string,
        color: string
      }
  • Success Response:

    • Code: 200 OK
      Content:
        {
            "name": "Car with new name",
            "color": "#ff00ff",
            "id": 2
        }
  • Error Response:

    • Code: 404 NOT FOUND
      Content:
        {}
  • Notes:

    None

Start / Stop Car's Engine

Starts or stops engine of specified car, and returns it's actual velocity and distance.

  • URL

    /engine

  • Method:

    PATCH

  • Headers:

    None

  • URL Params

    None

  • Query Params

    Required:

    id=[integer]

    status=['started'|'stopped']

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        {
          "velocity": 64,
          "distance": 500000
        }
  • Error Response:

    • Code: 400 BAD REQUEST
      Content:

      Wrong parameters: "id" should be any positive number, "status" should be "started", "stopped" or "drive"

    OR

    • Code: 404 NOT FOUND
      Content:

      Car with such id was not found in the garage.

  • Notes:

    None

Switch Car's Engine to Drive Mode

Switches engine of specified car to drive mode and finishes with success message or fails with 500 error.

  • URL

    /engine

  • Method:

    PATCH

  • Headers:

    None

  • URL Params

    None

  • Query Params

    Required:

    id=[integer]

    status=['drive']

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        {
          "success": true
        }
  • Error Response:

    • Code: 400 BAD REQUEST
      Content:

      Wrong parameters: "id" should be any positive number, "status" should be "started", "stopped" or "drive"

    OR

    • Code: 404 NOT FOUND
      Content:

      Engine parameters for car with such id was not found in the garage. Have you tried to set engine status to "started" before?

    OR

    • Code: 429 TOO MANY REQUESTS
      Content:

      Drive already in progress. You can't run drive for the same car twice while it's not stopped.

    OR

    • Code: 500 INTERNAL SERVER ERROR
      Content:

      Car has been stopped suddenly. It's engine was broken down.

  • Notes:

    • Before using this request you need to switch engine status to the 'started' status first.
    • Time when response will finish can be calculated using response from making engine 'started'.
    • Engine may fall randomly and at random time at the whole distance.

Get Winners

Returns json data about winners.

  • URL

    /winners

  • Method:

    GET

  • Headers:

    None

  • URL Params

    None

  • Query Params

    Optional:

    _page=[integer]

    _limit=[integer]

    _sort=['id'|'wins'|'time']

    _order=['ASC'|'DESC']

    If _limit param is passed api returns a header X-Total-Count that countains total number of records.

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        [
          {
            "id": 16,
            "wins": 1,
            "time": 2.92
          }
        ]
      Headers:
        "X-Total-Count": "4"
      
  • Error Response:

    None

  • Notes:

    None

Get Winner

Returns json data about specified winner.

  • URL

    /winners/:id

  • Method:

    GET

  • Headers:

    None

  • URL Params

    Required:

    id=[integer]

  • Query Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        {
            "id": 1,
            "wins": 1,
            "time": 10
        }
  • Error Response:

    • Code: 404 NOT FOUND
      Content:
        {}
  • Notes:

    None

Create Winner

Creates a new records in a winners table.

  • URL

    /winners

  • Method:

    POST

  • Headers:

    'Content-Type': 'application/json'

  • URL Params

    None

  • Query Params

    None

  • Data Params

      {
        id: number,
        wins: number,
        time: number
      }
  • Success Response:

    • Code: 201 CREATED
      Content:
        {
          "id": 109,
          "wins": 1,
          "time": 10
        }
  • Error Response:

    • Code: 500 INTERNAL SERVER ERROR
      Content:

      Error: Insert failed, duplicate id

  • Notes:

    None

Delete Winner

Delete specified car from a garage

  • URL

    /winners/:id

  • Method:

    DELETE

  • Headers:

    None

  • URL Params

    Required:

    id=[integer]

  • Query Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200 OK
      Content:
        {}
  • Error Response:

    • Code: 404 NOT FOUND
      Content:
        {}
  • Notes:

    None

Update Winner

Updates attributes of specified winner.

  • URL

    /winners/:id

  • Method:

    PUT

  • Headers:

    'Content-Type': 'application/json'

  • URL Params

    Required:

    id=[integer]

  • Query Params

    None

  • Data Params

      {
        wins: number,
        time: number
      }
  • Success Response:

    • Code: 200 OK
      Content:
        {
          "wins": 2,
          "time": 11,
          "id": 16
        }
  • Error Response:

    • Code: 404 NOT FOUND
      Content:
        {}
  • Notes:

    None