Skip to content

Instantly share code, notes, and snippets.

@Turbo87

Turbo87/api.md

Created May 14, 2015 11:18
Show Gist options
  • Save Turbo87/72d73a548dbf953e1f5e to your computer and use it in GitHub Desktop.
Save Turbo87/72d73a548dbf953e1f5e to your computer and use it in GitHub Desktop.
Download ZIP
Skylines API
Raw
api.md

Skylines API

Overview

Schema

  • API is only available over HTTPS at https://api.skylines.aero/
  • HTTP will show 404 Not Found
  • All data is sent and received as JSON
  • Blank fields are included as null
  • All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Authentication

  • Authentication failure results in 401 Unauthorized

  • Several failed authentication attemps result in temporary block for the user and 403 Forbidden

  • Missing resource access results in 404 Not Found or 403 Forbidden, depending on the resource

  • Three ways to authenticate:

Pagination

  • 30 items by default
  • ?page parameter to select page
  • ?page=1 is the first page
  • no ?page parameter means first page
  • ?per_page parameter to increase items per page limit (up to 100)

Link Header

  • Pagination info is included in the Link header
  • next, last, first, prev are supported rel values
Link: <https://api.skylines.aero/v1/flights?page=3&per_page=100>; rel="next",
      <https://api.skylines.aero/v1/flights?page=50&per_page=100>; rel="last"

Linebreak is included for readability.

Rate Limiting

  • Authenticated requests: 5.000 requests per hour and user
  • Unauthenticated requests: 60 requests per hour and IP
  • X-Rate-Limit-Limit header shows maximum number of requests that the consumer is permitted to make per hour - X-Rate-Limit-Remaining header shows number of requests remaining in the current rate limit window
  • X-Rate-Limit-Resetheader shows remaining time in seconds until the current rate limit window resets
  • Reached limit will result in 403 Forbidden

User Agent Required

  • User-Agent header is required and must not be empty
  • Request without User-Agent header is rejected with 403 Forbidden

Conditional requests

  • Resources return ETag and Last-Modified headers
  • Resource requests return 304 Not Modified if requested with matching If-None-Match or If-Modified-Since headers
  • 304 Not Modified responses do not count against the Rate Limit

Cross Origin Resource Sharing

  • Supported from any Origin
  • Requests with token may be limited to the Origin that created the token

JSONP

  • Supported through callback parameter
  • Data is enveloped in data property, headers and HTTP status code in meta

JSON Envelope

  • JSONP envelope sent as JSON with ?envelope=true
  • Always returns 200 Ok

Airfields

List airfields

GET /airfields

Get airfield

GET /airfields/:airfield_id

Airspace

List airspaces

GET /airspaces

Get airspace

GET /airspaces/:airspace_id

Events

(Experimental)

List events

GET /events

List events performed by a single user

GET /users/:user_id/events

List events for the authenticated user

GET /user/events

Flights

List flights

GET /flights

Get flight

GET /flights/:flight_id

Edit flight

PATCH /flights/:flight_id

Delete flight

DELETE /flights/:flight_id

List flight comments

GET /flights/:flight_id/comments

Add flight comment

POST /flights/:flight_id/comments

List flight phases

GET /flights/:flight_id/phases

List flight encounters

GET /flights/:flight_id/encounters

Groups/Clubs

List groups/clubs

GET /groups

List groups/clubs of a user

GET /users/:user_id/groups

List groups/clubs of the authenticated user

GET /user/groups

Get group/club

GET /groups/:group_id

Create group/club

POST /groups

Edit group/club

PATCH /groups/:group_id

Delete group/club

DELETE /groups/:group_id

List group/club members

GET /groups/:group_id/members

Add group/club member

PUT /groups/:group_id/members/:user_id

Remove group/club member

DELETE /groups/:group_id/members/:user_id

IGC Files

List IGC files

GET /igcs

Get IGC file

GET /igcs/:igc_id

Update IGC file

PATCH /igcs/:igc_id

Download IGC file

GET /igcs/:igc_id/content{?access_token=DOWNLOAD-TOKEN}

Upload IGC file(s)

POST /igcs

Also accepts archives with 1..n IGC files inside.

Live Tracking

(Experimental)

List live tracking sessions

GET /live

Get live tracking session

GET /live/:live_id

LiveTrack24

(Experimental)

GET /track.php
GET /client.php

Notifications

(Experimental)

List notifications for the authenticated user

GET /notifications

Mark notifications as read

PUT /notifications

Mark single notification as read

PATCH /notifications/:notification_id

Ranking

(Experimental)

Get user ranking

GET /ranking/users

Get club ranking

GET /ranking/clubs

Get airfield ranking

GET /ranking/airfields

Search

GET /search?q=abc123

Sessions

List (active) sessions

GET /sessions

Create session

POST /sessions

Get current session

GET /session

Delete current session

DELETE /session

Delete different session

DELETE /sessions/:session_id

Statistics

(Experimental)

Get global statistics

GET /statistics

Get user statistics

GET /users/:user_id/statistics

Get group/club statistics

GET /groups/:group_id/statistics

Users

List users

GET /users

Create user

POST /users

Get user

GET /users/:user_id

Get the followers of a user

GET /users/:user_id/followers

Get the users another user is following

GET /users/:user_id/following

Get the authenticated user

GET /user

Update the authenticated user

PATCH /user

Get the followers of the authenticated user

GET /user/followers

Get the users the authenticated user is following

GET /user/following

Follow a user

PUT /user/following/:user_id

Unfollow a user

DELETE /user/following/:user_id
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment