Skip to content

API.md

Jump to bottom
Syed Yead Zaman edited this page Oct 3, 2025 · 12 revisions

API Reference

Table of Contents

Rovers /api/rovers

Get all Rovers

GET /api/rovers

Retrieve a list of all rovers.

Response

  • 200 OK: Returns an object with a roversData array.

    • Example Response Body:

      {
  "roversData": [
    {
      "id": 1,
      "name": "Rover 1",
      "ipAddress": "192.168.1.10"
    },
    {
      "id": 2,
      "name": "Rover 2",
      "ipAddress": "192.168.1.11"
    }
  ]
}

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X GET http://localhost:5173/api/rovers

Create Rover

POST /api/rovers

Create a new rover.

Request Parameters

  • name (string, required): The name of the rover.
  • ipAddress (string, required): The IP address of the rover.

Response

  • 201 Created: Rover successfully created. Returns the created rover object.

    • Example Response Body:

      {
  "rover": {
    "id": 3,
    "name": "Test Rover",
    "ipAddress": "192.168.1.100"
  }
}

  • 400 Bad Request: Missing required fields.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X POST http://localhost:5173/api/rovers \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Rover", "ipAddress": "192.168.1.100"}'

Rovers by ID /api/rovers/[id]

Get Rover by ID

GET /api/rovers/[id]

Retrieve a specific rover by its ID.

Response

  • 200 OK: Returns the rover object.

    • Example Response Body:

      {
  "id": 1,
  "name": "Rover 1",
  "ipAddress": "192.168.1.10"
}

  • 400 Bad Request: Invalid ID format.

  • 404 Not Found: Rover not found.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X GET http://localhost:5173/api/rovers/1

Delete Rover by ID

DELETE /api/rovers/[id]

Delete a specific rover by its ID.

Response

  • 200 OK: Rover successfully deleted. Returns a success message.

    • Example Response Body:

      {
  "message": "Rover deleted successfully"
}

  • 400 Bad Request: Invalid ID format.

  • 404 Not Found: Rover not found.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X DELETE http://localhost:5173/api/rovers/1

Paths /api/paths

Paths are special because they use the unsupported data type which is LineString. This means that you will need to use raw SQL queries to interact with this table. Luckily, the endpoints take care of this for you as they will be parsed in the GeoJSON format.

Get all Paths

GET /api/paths

Retrieve a list of all paths.

Response

  • 200 OK: Returns an array of path objects.

    • Example Response Body:

      [
{
    "id": 2,
    "rover_id": 2,
    "timestamp": "2025-09-14 17:51:45.658099+00",
    "route": {
    "type": "LineString",
    "coordinates": [
        [
        -73.55,
        45.49
        ],
        [
        -73.54,
        45.48
        ]
    ]
    }
},
{
    "id": 1,
    "rover_id": 1,
    "timestamp": "2025-09-14 17:51:45.658099+00",
    "route": {
    "type": "LineString",
    "coordinates": [
        [
        -73.57,
        45.5
        ],
        [
        -73.58,
        45.51
        ]
    ]
    }
}
]

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X GET http://localhost:5173/api/paths

Create Path

POST /api/paths

Create a new path. Will return the created path object.

Request Parameters

  • rover_id (integer, required): The ID of the rover associated with the path.
  • route (GeoJSON LineString, required): The route of the path in GeoJSON LineString format.

Response

  • 201 Created: Path successfully created. Returns the created path object.

    • Example Response Body:

      {
    "id": 3,
    "rover_id": 1,
    "timestamp": "2023-10-01T12:34:56.789Z",
    "route": {
        "type": "LineString",
        "coordinates": [
            [-73.57, 45.5],
            [-73.58, 45.51]
        ]
    }
}

  • 400 Bad Request: Missing required fields or invalid data.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X POST http://localhost:5173/api/paths \
    -H "Content-Type: application/json" \
    -d '{
    "rover_id": 1,
    "route": {
        "type": "LineString",
        "coordinates": [
            [-73.57, 45.5],
            [-73.58, 45.51]
        ]
    }
    }'

Get Path by ID

GET /api/paths/[id]

Retrieve a specific path by its ID.

Response

  • 200 OK: Returns the path object.

    • Example Response Body:

      {
    "id": 1,
    "rover_id": 1,
    "timestamp": "2023-10-01T12:34:56.789Z",
    "route": {
        "type": "LineString",
        "coordinates": [
            [-73.57, 45.5],
            [-73.58, 45.51]
        ]
    }
}

  • 400 Bad Request: Invalid ID format.

  • 404 Not Found: Path not found.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X GET http://localhost:5173/api/paths/1

Delete Path by ID

DELETE /api/paths/[id]

Delete a specific path by its ID.

Response

  • 204 No Content: Path successfully deleted.
  • 400 Bad Request: Invalid ID format.
  • 404 Not Found: Path not found.
  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X DELETE http://localhost:5173/api/paths/1

Images /api/images

Get all Images

GET /api/images

Retrieve a list of all uploaded images.

Response

  • 200 OK: Returns an array of image objects.

    • Example Response Body:

      [
    {
        "id": 1,
        "filePath": "/uploads/image1.jpg",
        "uploadedAt": "2023-10-01T12:34:56.789Z"
    },
    {
        "id": 2,
        "filePath": "/uploads/image2.jpg",
        "uploadedAt": "2023-10-02T12:34:56.789Z"
    }
]

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X GET http://localhost:5173/api/images

Create Image

POST /api/images

Create a new image with upload. Image currently saved at /uploads directory. Will return the ID of the created image.

Request Parameters

  • image (file, required): The image file to upload.

Response

  • 201 Created: Image successfully created. Returns the ID of the created image.

    • Example Response Body:

      {
    "image_id": 1
}

  • 400 Bad Request: Missing required fields.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X POST http://localhost:5173/api/images \
    -F "image=@/home/syeadz/Downloads/cat.jpeg"

Notes

  • There is currently an issue with cross-site form submissions. It has been turned off for now, but would be required for production.
  • The path ID is figured out from the rover which is currently on a path.
  • The location is figured out from the rover's current GPS coordinates.

Get Image by ID

GET /api/images/[id]

Retrieve a specific image by its ID.

Response

  • 200 OK: Returns the image object.

    • Example Response Body:

      {
    "id": 1,
    "filePath": "/uploads/image1.jpg",
    "uploadedAt": "2023-10-01T12:34:56.789Z"
}

  • 400 Bad Request: Invalid ID format.

  • 404 Not Found: Image not found.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X GET http://localhost:5173/api/images/1

Delete Image by ID

DELETE /api/images/[id]

Delete a specific image by its ID.

Response

  • 204 No Content: Image successfully deleted.
  • 400 Bad Request: Invalid ID format.
  • 404 Not Found: Image not found.
  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X DELETE http://localhost:5173/api/images/1

Detections /api/detections

Get all Detections

GET /api/detections

Retrieve a list of all detections.

Response

  • 200 OK: Returns an array of detection objects.

    • Example Response Body:

      [
    {
        "id": 1,
        "imageId": 1,
        "bbox": "(100,150,200,250)",
        "confidence": 0.92,
        "areaScore": 85,
        "depthScore": 90,
        "falsePositive": false
    },
    {
        "id": 2,
        "imageId": 1,
        "bbox": "(50,75,150,175)",
        "confidence": 0.85,
        "areaScore": 80,
        "depthScore": 85,
        "falsePositive": true
    }
]

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X GET http://localhost:5173/api/detections

Create Detection

POST /api/detections

Create a new detection associated with an image. Will return the ID of the created detection.

Request Parameters

  • image_id (integer, required): The ID of the image to associate with the detection.
  • bbox (array, required): The bounding box for the detection in the format [x_min, y_min, x_max, y_max].
  • confidence (float, required): The confidence score for the detection.
  • area_score (integer, optional): The area score for the detection.
  • depth_score (integer, optional): The depth score for the detection.
  • false_positive (boolean, optional): Whether the detection is a false positive.

Response

  • 201 Created: Detection successfully created. Returns the ID of the created detection.

    • Example Response Body:

      {
    "detection_id": 1
}

  • 400 Bad Request: Missing required fields or invalid data.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X POST http://localhost:5173/api/detections \
    -H "Content-Type: application/json" \
    -d '{
    "image_id": 1,
    "confidence": 0.92,
    "bbox": [100, 150, 200, 250]
    }'

Notes

  • Ensure that the image_id provided exists in the database.
  • The bbox should be an array of four numbers representing the coordinates of the bounding box.
  • The confidence should be a float value between 0 and 1.
  • Optional fields can be omitted if not applicable.

Get Detection by ID

GET /api/detections/[id]

Retrieve a specific detection by its ID.

Response

  • 200 OK: Returns the detection object.

    • Example Response Body:

      {
    "id": 1,
    "imageId": 1,
    "bbox": "(100,150,200,250)",
    "confidence": 0.92,
    "areaScore": 85,
    "depthScore": 90,
    "falsePositive": false
}

Update Detection Scores by ID

PATCH /api/detections/[id]

Update the area score and/or depth score for a specific detection.

Request Parameters

  • areaScore (integer, optional): The updated area score for the detection.
  • depthScore (integer, optional): The updated depth score for the detection.

Response

  • 200 OK: Detection scores successfully updated.

    • Example Response Body:

      {
    "id": 1,
    "imageId": 1,
    "bbox": "(100,150,200,250)",
    "confidence": 0.92,
    "areaScore": 85,
    "depthScore": 90,
    "falsePositive": false,
}

  • 400 Bad Request: Missing required fields or invalid data.

  • 404 Not Found: Detection not found.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X PATCH http://localhost:5173/api/detections/1 \
    -H "Content-Type: application/json" \
    -d '{
        "areaScore": 85,
        "depthScore": 90,

        "falsePositive": 1
    }'

Notes

  • Ensure that the detection ID provided in the URL exists in the database.
  • The areaScore and depthScore should be integer values between 0 and 100.
  • falsePositive should be an integer value of either 0 (false) or 1 (true).
  • You can update as many valid fields as you want in a single request.
  • It's not possible to update other fields (like imageId, confidence, or bbox) using this endpoint.

Delete Detection by ID

DELETE /api/detections/[id] Delete a specific detection by its ID.

Response

  • 200 OK: Detection successfully deleted. Returns a success message.

    • Example Response Body:

      {
    "message": "Detection deleted successfully"
}

  • 400 Bad Request: Invalid ID format.

  • 404 Not Found: Detection not found.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X DELETE http://localhost:5173/api/detections/1

Logs /api/rovers/[id]/logs

Create Log

POST /api/rovers/[id]/logs

Create a new log entry for a specific rover.

Request Parameters

  • latitude (float, required): The latitude of the rover.
  • longitude (float, required): The longitude of the rover.
  • altitude (float, required): The altitude of the rover.
  • roll (float, required): The roll of the rover.
  • pitch (float, required): The pitch of the rover.
  • yaw (float, required): The yaw of the rover.
  • temperature (float, required): The temperature of the rover.
  • voltage (float, required): The voltage of the rover.

Response

  • 201 Created: Log entry successfully created. Returns the created log object.

    • Example Response Body:

      {
    "id": 1,
    "rover_id": 1,
    "timestamp": "2023-10-01T12:34:56.789Z",
    "latitude": 45.5017,
    "longitude": -73.5673,
    "altitude": 10.5,
    "roll": 0.0,
    "pitch": 0.0,
    "yaw": 90.0,
    "temperature": 22.5,
    "voltage": 12.6
}

  • 400 Bad Request: Missing required fields or invalid data.

  • 500 Internal Server Error: An error occurred on the server.

Example Request

Example using curl:

curl -X POST http://localhost:5173/api/rovers/1/logs \
    -H "Content-Type: application/json" \
    -d '{
    "latitude": 45.5017,
    "longitude": -73.5673,
    "altitude": 10.5,
    "roll": 0.0,
    "pitch": 0.0,
    "yaw": 90.0,
    "temperature": 22.5,
    "voltage": 12.6
    }'

Clone this wiki locally