From 02c6bd7cbe63c98932fc4be7b8d12bf7bff1a434 Mon Sep 17 00:00:00 2001
From: Nabeel Shahzad <nshahzad@gmail.com>
Date: Tue, 9 Jan 2018 13:44:04 -0600
Subject: [PATCH] add api page to docs

---
 docs/api.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 228 insertions(+)
 create mode 100644 docs/api.md

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 00000000..191213b1
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,228 @@
+phpVMS has a REST-api for integration with any standalone programs, including any flight simulator addons, or ACARS applications.
+
+# Authentication and Authorization
+
+Each user is given an API key (and can regenerate it) when they register. Requests to a phpVMS API will require an `X-API-Key` header, with this key. Addons can take advantage of this by adding the `api.auth` middleware to their route group.
+
+### Headers Example
+
+```http
+X-API-Key: {user API key}
+Content-type: application/json
+```
+
+## Sample cURL Request
+
+```php
+$api_key = 'YOUR API KEY';
+$url = "http://your-site.com/api/user";
+$headers = [
+    'X-API-Key:' . $api_key,
+    'Content-type:application/json',
+];
+
+$ch = curl_init();
+
+curl_setopt($ch,CURLOPT_URL,$url);
+curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
+curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
+
+json_response = \json_decode(curl_exec($ch));
+curl_close($ch);
+
+echo $json_response;
+```
+## Types
+
+Not all IDs are numeric integers. At the moment, the primary keys on these tables are strings. They are hashed IDs that are generated:
+
+* acars
+* flights
+* pireps
+
+## Errors
+
+Where possible, the standard HTTP error codes are followed and returned, with extra information in the body, if available.
+
+### Unauthorized
+
+`401` is returned if the API key is invalid, or the user is disallowed from API access. The `message` parameter will offer more error.
+
+### Not Found
+
+`404` is returned if an entity is not found
+
+### Validation Errors
+
+`400`, with details in the `message` parameter about the bad input.
+
+## Pagination
+
+Where indicated, pagination is enabled/available. When calling those APIs, the data is returned in this format:
+
+- `data` contains a list of all of the objects (for example, the airports)
+- `links` contains the links to navigate through the paginated list
+- `meta` contains information about the current dataset
+
+```json
+{ 
+  "data": [ ... ],
+  "links": {
+    "first":"http://phpvms.test/api/airports?page=1",
+    "last":"http://phpvms.test/api/airports?page=3",
+    "prev":null,
+    "next":"http://phpvms.test/api/airports?page=2"
+  },
+  "meta": {
+    "current_page": 1,
+    "from":1, 
+    "last_page":3,
+    "path":"http://phpvms.test/api/airports",
+    "per_page":50,
+    "to":50,
+    "total":120
+  }
+}
+```
+
+# APIs Available
+
+## User
+
+```http
+GET /api/user - Returns the user's information, including bids, etc
+```
+
+***
+
+## Airlines
+
+```http
+GET /api/airlines
+```
+Get all of the airlines
+
+```http
+GET /api/airlines/{ID}
+```
+Get information about a specific airline
+
+***
+
+## Airports
+
+```http
+GET /api/airports
+```
+Get all of the airports, paginated list
+
+```http
+GET /api/airports/hubs
+```
+Get all of the hubs, paginated list
+
+```http
+GET /api/airports/{ICAO}
+```
+Get the details about an airport
+
+```http
+GET /api/airports/{ICAO}/lookup
+```
+Get the details about an airport, but proxies the call to vaCentral
+
+***
+
+## Fleet
+
+```http
+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}
+````
+Return information about an aircraft, including the subfleet information
+
+Query string parameters: `?type=registration|tail_number|icao`. Default/blank is the DB ID
+
+***
+
+## Flights
+
+
+```http
+GET /api/flights
+```
+Return all of the flights, paginated
+
+
+```http
+GET /api/flights/{FLIGHT ID}
+```
+Return details about a given flight
+
+
+```http
+GET /api/flights/search
+```
+Do a search for a flight
+
+Query String Example:
+`/api/flights/search?depicao=KJFK&arricao=KAUS`
+
+  - `airline_id` - ID of the airline
+  - `dep_icao` - Departure airport code
+  - `arr_icao` - Arrival airport code
+  - `flight_number` - Can be a partial match
+  - `route_code`
+
+***
+
+## PIREPs
+
+```http
+GET /api/pireps/{PIREP ID}
+```
+Retrieve the PIREP information
+
+```http
+GET /api/pireps/{PIREP ID}/route
+```
+Retrieve the route
+
+```http
+GET /api/pireps/{PIREP ID}/acars/geojson
+```
+Get the ACARS data in GeoJSON format
+
+```http
+GET /api/pireps/{PIREP ID}/acars/positions
+```
+Get the ACARS data in plain rows
+
+[See the ACARS documentation](https://github.com/nabeelio/phpvms/wiki/acars) for details about the PIREPs and ACARS API details
+
+***
+
+## Users
+
+```http
+GET /api/users/{id}
+```
+Retrieve info about a user
+
+```http
+GET /api/users/{id}/bids
+```
+Get a user's bids
+
+***
+
+## Settings
+
+```http
+GET /api/settings
+```
+Get all of the phpVMS configuration settings, including things like the units and individual configuration options. [See the list of settings here](https://github.com/nabeelio/phpvms/blob/master/app/Database/migrations/2017_06_07_014930_create_settings_table.php#L41). Remember to look at the `type` column in order to properly parse the value.