From 2e914ae12dc0acb4b8427bd67144351de6efec7d Mon Sep 17 00:00:00 2001 From: Nabeel Shahzad Date: Tue, 9 Jan 2018 14:06:35 -0600 Subject: [PATCH] Add examples to the REST API docs --- docs/api.md | 282 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 257 insertions(+), 25 deletions(-) diff --git a/docs/api.md b/docs/api.md index 191213b1..8603c54e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -89,64 +89,296 @@ Where indicated, pagination is enabled/available. When calling those APIs, the d ## User -```http -GET /api/user - Returns the user's information, including bids, etc -``` +### GET /api/user +Returns the user's information, including bids, etc. Example response: + +```json +{ + "id":2, + "name":"Adam Lockman PhD", + "email":"miles.sporer@example.net", + "apikey":null, + "rank_id":"1", + "home_airport": "KJFK", + "curr_airport": "KJFK", + "last_pirep_id": 1, + "flights":0, + "flight_time":914, + "balance":0, + "timezone": "American/Chicago", + "status":0, + "state":1, + "airline":{ + "id":1, + "icao":"VMS", + "iata":"VMS", + "name":"phpVMS Airlines", + "country":"United States", + "logo":null + }, + "bids":[ + + ], + "rank":{ + "name":"New Pilot", + "subfleets":[ + + ] + } +} +``` *** ## Airlines -```http -GET /api/airlines -``` -Get all of the airlines +### GET /api/airlines -```http -GET /api/airlines/{ID} +Get all of the airlines. Paginated + +```json +{ + "data":[ + { + "id":1, + "icao": "VMS", + "iata": "VMS", + "name": "phpVMS Airlines", + "country": "United States", + "logo": null + } + ], + "links":{ + "first":"http://phpvms.test/api/airlines?page=1", + "last":"http://phpvms.test/api/airlines?page=1", + "prev":null, + "next":null + }, + "meta":{ + "current_page":1, + "from":1, + "last_page":1, + "path":"http://phpvms.test/api/airlines", + "per_page":50, + "to":1, + "total":1 + } +} ``` + +### GET /api/airlines/{ID} + Get information about a specific airline +```json +{ + "id":1, + "icao": "VMS", + "iata": "VMS", + "name": "phpVMS Airlines", + "country": "United States", + "logo": null +} +``` + *** ## Airports -```http -GET /api/airports -``` +### GET /api/airports + Get all of the airports, paginated list -```http -GET /api/airports/hubs +```json +{ + "data":[ + { + "id":"KJFK", + "iata":"KJFK", + "icao":"KJFK", + "name":"John F Kennedy International Airport", + "city":"New York", + "country":"United States", + "location":null, + "hub": true, + "fuel_100ll_cost": 0.00, + "fuel_jeta_cost": 0.00, + "fuel_mogas_cost": 0.00, + "tz":"America/New_York", + "lat":40.6398, + "lon":-73.7789 + } + ], + "links":{ + "first":"http://phpvms.test/api/airports?page=1", + "last":"http://phpvms.test/api/airports?page=2", + "prev":null, + "next":"http://phpvms.test/api/airports?page=2" + }, + "meta":{ + "current_page":1, + "from":1, + "last_page":2, + "path":"http://phpvms.test/api/airports", + "per_page":50, + "to":2, + "total":2 + } +} ``` + +### GET /api/airports/hubs + Get all of the hubs, paginated list -```http -GET /api/airports/{ICAO} +```json +{ + "data":[ + { + "id":"KJFK", + "iata":"KJFK", + "icao":"KJFK", + "name":"John F Kennedy International Airport", + "city":"New York", + "country":"United States", + "location":null, + "hub": true, + "fuel_100ll_cost": 0.00, + "fuel_jeta_cost": 0.00, + "fuel_mogas_cost": 0.00, + "tz":"America/New_York", + "lat":40.6398, + "lon":-73.7789 + } + ], + "links":{ + "first":"http://phpvms.test/api/airports?page=1", + "last":"http://phpvms.test/api/airports?page=2", + "prev":null, + "next":"http://phpvms.test/api/airports?page=2" + }, + "meta":{ + "current_page":1, + "from":1, + "last_page":2, + "path":"http://phpvms.test/api/airports", + "per_page":50, + "to":2, + "total":2 + } +} ``` + +### GET /api/airports/{ICAO} + Get the details about an airport -```http -GET /api/airports/{ICAO}/lookup +```json +{ + "id":"KJFK", + "iata":"KJFK", + "icao":"KJFK", + "name":"John F Kennedy International Airport", + "city":"New York", + "country":"United States", + "location":null, + "hub": true, + "fuel_100ll_cost": 0.00, + "fuel_jeta_cost": 0.00, + "fuel_mogas_cost": 0.00, + "tz":"America/New_York", + "lat":40.6398, + "lon":-73.7789 +} ``` -Get the details about an airport, but proxies the call to vaCentral *** ## Fleet -```http -GET /api/fleet -``` +### GET /api/fleet + Get all of the subfleets and aircraft under the fleet. Includes the fare and airline information. Paginated -```http -GET /api/aircraft/{id} -```` +```json +{ + "data":[ + { + "id":1, + "airline_id":1, + "name":"Boeing 747-400", + "type":"B744", + "fuel_type":null, + "cargo_capacity":null, + "fuel_capacity":null, + "gross_weight":null, + "aircraft":[ + { + "id":1, + "subfleet_id":"1", + "icao":"B744", + "airport_id":"KJFK", + "hex_code":null, + "name":"Boeing 747 \"The Queen\"", + "registration":"NC17", + "tail_number":"17", + "active":true, + "created_at":"2018-01-08 21:37:13", + "updated_at":"2018-01-08 21:37:13" + } + ] + } + ], + "links":{ + "first":"http://phpvms.test/api/fleet?page=1", + "last":"http://phpvms.test/api/fleet?page=1", + "prev":null, + "next":null + }, + "meta":{ + "current_page":1, + "from":1, + "last_page":1, + "path":"http://phpvms.test/api/fleet", + "per_page":50, + "to":2, + "total":2 + } +} +``` + +### GET /api/aircraft/{id} + Return information about an aircraft, including the subfleet information Query string parameters: `?type=registration|tail_number|icao`. Default/blank is the DB ID +```json +{ + "id":1, + "subfleet_id":"1", + "icao":"B744", + "airport_id":"KJFK", + "hex_code":null, + "name":"Boeing 747 \"The Queen\"", + "registration":"NC17", + "tail_number":"17", + "active":true, + "subfleet": { + "id":1, + "airline_id":1, + "name":"Boeing 747-400", + "type":"B744", + "fuel_type":null, + "cargo_capacity":null, + "fuel_capacity":null, + "gross_weight":null + }, + "created_at":"2018-01-08 21:37:13", + "updated_at":"2018-01-08 21:37:13" +} +``` + *** ## Flights