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.

Health Check & Keep Alive

This API includes a health check endpoint at /health that returns server status information. This is particularly useful for preventing cold starts on hosting platforms like Render.com.

Setting up Keep Alive on Render.com

1. Deploy your app to Render.com using the free tier
2. Set up GitHub repository secret:
   • Go to your GitHub repository settings
   • Navigate to "Secrets and variables" → "Actions"
   • Add a new secret named RENDER_URL with your Render app URL (e.g., https://your-app-name.onrender.com)
3. Enable GitHub Actions (the workflow file is already included in .github/workflows/keep-alive.yml)

The GitHub Action will automatically ping your health check endpoint every 14 minutes to prevent the free tier from going to sleep (which happens after 15 minutes of inactivity).

Health Check Endpoint

• URL: /health
• Method: GET
• Response:

{
  "status": "OK",
  "timestamp": "2025-08-03T10:30:00.000Z",
  "uptime": 1234.567,
  "environment": "production"
}

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