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

• Garage
  • Get Cars
  • Get Car
  • Create Car
  • Delete Car
  • Update Car
• Engine
  • Start / Stop Car's Engine
  • Switch Car's Engine to Drive Mode
• Winners
  • Get Winners
  • Get Winner
  • Create Winner
  • Delete Winner
  • Update Winner

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 the 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 the 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 the specified car from the winners table.

• 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 the 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