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

### 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

### GET /api/airlines

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

### GET /api/airports

Get all of the airports, paginated list

```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

```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

```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
}
```

***

## Fleet

### GET /api/fleet

Get all of the subfleets and aircraft under the fleet. Includes the fare and airline information. Paginated

```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

### GET /api/flights

Return all of the flights, paginated

### GET /api/flights/{FLIGHT ID}

Return details about a given flight

### 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

### GET /api/pireps/{PIREP ID}

Retrieve the PIREP information

### GET /api/pireps/{PIREP ID}/route

Retrieve the route

### GET /api/pireps/{PIREP ID}/acars/geojson

Get the ACARS data in GeoJSON format

### 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

### GET /api/users/{id}

Retrieve info about a user

### GET /api/users/{id}/bids

Get a user's bids

***

## Settings

### 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.