Skip to main content

​
Introduction

The Ghost Planet API is a RESTful JSON API built with Go that provides access to paranormal investigation data, including locations, evidence, and investigations. The API uses standard HTTP methods and returns JSON responses with a consistent envelope format.

​
Base URL

All API requests should be made to: 
http://localhost:4000/v1
The API runs on port 4000 by default in development mode. The base path /v1 indicates API version 1.0.0.

​
API Version

The current API version is 1.0.0. The version is included in the base path (/v1/) and can be verified via the healthcheck endpoint. Source: backend/cmd/api/main.go:18

​
Server Configuration

The API server is configured with the following default settings:
  • Port: 4000 (configurable via -port flag)
  • Environment: development (configurable via -env flag)
  • Read Timeout: 10 seconds
  • Write Timeout: 30 seconds
  • Idle Timeout: 1 minute
  • Database: PostgreSQL with connection pooling
    • Max Open Connections: 25
    • Max Idle Connections: 25
    • Max Idle Time: 15 minutes
Source: backend/cmd/api/main.go:40-74

​
Response Format

All API responses use a JSON envelope format for consistency and extensibility.

​
Success Response Structure

Successful responses wrap data in a descriptive key: 
{
  "location": {
    "id": 1,
    "name": "Haunted Manor",
    "address": "123 Spooky St, Albuquerque, NM",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "visibility": true
  }
}
The envelope format uses an indented JSON structure with tabs for readability. All responses end with a newline character.

​
Response Headers

All JSON responses include: 
Content-Type: application/json
Source: backend/cmd/api/helpers.go:27-46

​
Error Responses

Error responses follow a consistent format with an error key: 
{
  "error": "the requested resource could not be found"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
Status CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request format or parameters
404Not FoundResource not found
405Method Not AllowedHTTP method not supported for this endpoint
422Unprocessable EntityValidation failed
500Internal Server ErrorServer encountered an error

​
Error Types

The API returns different error messages based on the error type: 
{
  "error": "the requested resource could not be found"
}
Validation errors (422) return a map of field names to error messages, while other errors return a single string message.
Source: backend/cmd/api/errors.go:12-45

​
Request Limits

​
Request Body Size

The API enforces a maximum request body size:
  • Maximum Size: 1 MB (1,048,576 bytes)
Requests exceeding this limit will receive a 400 Bad Request error: 
{
  "error": "body must not be larger than 1048576 bytes"
}
Source: backend/cmd/api/helpers.go:49

​
Request Body Validation

The API strictly validates JSON requests:
  • Request body must contain valid JSON
  • Unknown fields are rejected
  • Field types must match expected types
  • Body must contain exactly one JSON value
  • Empty bodies are rejected
curl -X POST http://localhost:4000/v1/locations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Abandoned Hospital",
    "address": "456 Dark Ave",
    "latitude": 34.0522,
    "longitude": -118.2437,
    "visibility": true
  }'
Source: backend/cmd/api/helpers.go:48-99

​
Health Check

Use the health check endpoint to verify API availability: 
curl http://localhost:4000/v1/healthcheck
Response: 
{
  "status": "available",
  "system_info": {
    "status": "available",
    "environment": "development",
    "version": "1.0.0"
  }
}
Source: backend/cmd/api/healthcheck.go:7-21

​
Content Type

All requests with a body must include the appropriate Content-Type header: 
Content-Type: application/json
The API only accepts JSON payloads. Other content types will be rejected.

​
Router

The API uses httprouter for fast HTTP routing with support for URL parameters and automatic OPTIONS responses. Source: backend/cmd/api/routes.go:9

Build docs developers (and LLMs) love

Get started for freeTalk to us