Skip to content

AIRPLANE_API.md

Latest commit

 

History

History
224 lines (170 loc) · 4.96 KB

AIRPLANE_API.md

File metadata and controls

224 lines (170 loc) · 4.96 KB
Raw

Airplane API Documentation

Overview

The Airplane API provides CRUD operations for managing airplane data from OpenSky Network. All airplane data is stored in the MySQL database and can be queried, created, updated, and deleted through RESTful endpoints.

Base URL

http://localhost:8080/api/airplanes

Endpoints

1. Get All Airplanes

GET /api/airplanes

Returns all airplanes in the database.

Response:

[
  {
    "id": 1,
    "icao24": "a12345",
    "callsign": "UAL123",
    "originCountry": "United States",
    "aircraftType": "Large",
    "latitude": 40.6413,
    "longitude": -73.7781,
    "altitude": 35000,
    "groundspeed": 450,
    "heading": 90,
    "verticalRate": 0.0,
    "onGround": false,
    "squawk": "1200",
    "lastContact": 1707654321,
    "createdAt": "2024-02-11T10:00:00",
    "updatedAt": "2024-02-11T10:05:00"
  }
]

2. Get Airplane by ID

GET /api/airplanes/{id}

Returns a specific airplane by its database ID.

3. Get Airplane by ICAO24

GET /api/airplanes/icao24/{icao24}

Returns an airplane by its ICAO24 address (unique identifier).

4. Get Airplane by Callsign

GET /api/airplanes/callsign/{callsign}

Returns an airplane by its callsign.

5. Get Airplanes by Country

GET /api/airplanes/country/{country}

Returns all airplanes from a specific origin country.

6. Get Airplanes by Type

GET /api/airplanes/type/{type}

Returns all airplanes of a specific aircraft type.

7. Get Airplanes by Ground Status

GET /api/airplanes/ground?status={true|false}

Returns airplanes filtered by ground status.

Parameters:

  • status (boolean): true for on-ground, false for in-flight

8. Get Airplanes Within Bounds

GET /api/airplanes/bounds?minLat={minLat}&maxLat={maxLat}&minLng={minLng}&maxLng={maxLng}

Returns airplanes within a geographic bounding box.

Parameters:

  • minLat (double): Minimum latitude
  • maxLat (double): Maximum latitude
  • minLng (double): Minimum longitude
  • maxLng (double): Maximum longitude

9. Get Airplanes with Recent Contact

GET /api/airplanes/recent?timestamp={timestamp}

Returns airplanes that have been contacted after the specified timestamp.

Parameters:

  • timestamp (long): Unix timestamp in seconds

10. Create Airplane

POST /api/airplanes

Creates a new airplane record.

Request Body:

{
  "icao24": "a12345",
  "callsign": "UAL123",
  "originCountry": "United States",
  "aircraftType": "Large",
  "latitude": 40.6413,
  "longitude": -73.7781,
  "altitude": 35000,
  "groundspeed": 450,
  "heading": 90,
  "verticalRate": 0.0,
  "onGround": false,
  "squawk": "1200",
  "lastContact": 1707654321
}

11. Upsert Airplane

POST /api/airplanes/upsert

Creates a new airplane or updates an existing one based on ICAO24 address.

Request Body: Same as Create Airplane

12. Batch Upsert Airplanes

POST /api/airplanes/batch

Creates or updates multiple airplanes in a single request.

Request Body:

[
  {
    "icao24": "a12345",
    "callsign": "UAL123",
    ...
  },
  {
    "icao24": "b67890",
    "callsign": "DAL456",
    ...
  }
]

13. Update Airplane

PUT /api/airplanes/{id}

Updates an existing airplane by ID.

Request Body: Same as Create Airplane

14. Delete Airplane

DELETE /api/airplanes/{id}

Deletes an airplane by ID.

15. Delete Old Airplanes

DELETE /api/airplanes/old?timestamp={timestamp}

Deletes all airplanes with last contact before the specified timestamp.

Parameters:

  • timestamp (long): Unix timestamp in seconds

Database Schema

CREATE TABLE airplanes (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    icao24 VARCHAR(6) NOT NULL UNIQUE,
    callsign VARCHAR(10),
    origin_country VARCHAR(100),
    aircraft_type VARCHAR(50),
    latitude DOUBLE,
    longitude DOUBLE,
    altitude INT,
    groundspeed INT,
    heading INT,
    vertical_rate DOUBLE,
    on_ground BOOLEAN DEFAULT FALSE,
    squawk VARCHAR(4),
    last_contact BIGINT,
    created_at DATETIME NOT NULL,
    updated_at DATETIME,
    INDEX idx_icao24 (icao24),
    INDEX idx_callsign (callsign),
    INDEX idx_location (latitude, longitude),
    INDEX idx_last_contact (last_contact)
);

Frontend Integration

Use the airplaneapi.js service to interact with the API:

import airplaneAPIService from './services/api/airplaneapi';

// Save OpenSky flights to database
const flights = await openskyapi.getStates(bounds);
await airplaneAPIService.saveOpenSkyFlights(flights.flights);

// Get all airplanes
const airplanes = await airplaneAPIService.getAllAirplanes();

// Get airplanes within bounds
const airplanesInBounds = await airplaneAPIService.getAirplanesWithinBounds(bounds);

Setup Instructions

  1. Run the database setup script:
mysql -u root -p < backend/database-setup.sql
  1. Start the backend server:
cd backend
mvn spring-boot:run
  1. The API will be available at http://localhost:8080/api/airplanes