Skip to content

Latest commit

 

History

History
109 lines (75 loc) · 3.73 KB

REST.md

File metadata and controls

109 lines (75 loc) · 3.73 KB
Raw

Drone API

This is a sketch of the REST API for drone operations. For the actual API documentation see the autogenerated swagger docs.

API keys

All API calls must include an API key. The key can be provided either in an authentication header (recommended) or as a query parameter:

Auth header example: Authorization: DroneApi apikey="myappid.mymapkey"

Query parameter example: http://nestor.3dr.com/api/v1/mission?api_key=myappid.myappkey

Standard query arguments

All of the following endpoints support the following query strings:

    queryParam[Option[Int]]("page_offset").description("If paging, the record # to start with (use 0 at start)"),
    queryParam[Option[Int]]("page_size").description("If paging, the # of records in the page"),
    queryParam[Option[String]]("order_by").description("To get sorted response, the field name to sort on"),
    queryParam[Option[String]]("order_dir").description("If sorting, the optional direction.  either asc or desc")))

/user

GET /user//

where property is:

  • vehicles - returns a JSON array of vehicle IDs for this user (eventually support query params for filtering)

PUT /user/ - create new user with the specified ID (this operation is allowed for even non logged in users) POST /user//vehicles - creates a new vehicle

/vehicle

GET /vehicle//

where property is:

  • missions - returns a JSON array of mission IDs for this vehicle (eventually support query params for filtering)

POST /vehicle//missions - create a new mission, payload is expected to be a tlog, log or bog

/mission

GET /mission//

where property is:

  • mode
  • location
  • messages.tlog (raw tlog data)
  • messages.json (a json encoding of messages)
  • messages.kmz
  • messages.gmaps.kmz (kmz but obeying the limits associated with gmaps) (FIXME - store in local DB?)
  • messages.jpg (a jpg thumbnail view of the flight)
  • parameters.json (a json representation of vehicle parameters)
  • parameters.complete (a complete param file)
  • parameters.share (a param file with 'vehicle specific' parameters stripped)
  • waypoints (a json representation of waypoints)
  • dseries (a temporary json representatio to support the old droneshare interface)

/session Logging in

POST /session/login

Login using the login and password parameters

GET /session/user

Get the logged in user object (or Forbidden 403)

POST /session/logout

To logout

Cookies are optionally supported, if your client uses cookies you can log in the user once and just attach the cookie to future operations. If you do not support cookies, you'll need to attach login & password as query params for all operations.

/admin Administration operations

Various private admin functions sit here.

/admin/sim

There is a fairly extensive vehicle simulator.

GET http://localhost:8080/api/v1/admin/sim/std/KEEP/NUMVEHICLES/NUMSECS?api_key=eb34bd67.megadroneshare

Where:

  • KEEP is true/false for keeping the missions after the run is over
  • NUMVEHICLES is the number of sim vehicles to create
  • NUMSECS is the number of seconds to keep those vehicles running

TODO

  • http://localhost:8080/view/5n72bt make it work using only the mission URL

  • deploy to 3dr server

  • turn on exception notification via pushover or bugsense or takipi

  • change droneshare to be entirely a javascript app

  • make mission API work with live flights also

  • use atmosphere+scalatra for async update

  • Turn on CI server (after I figure out how to use a test DB)

  • check for user perms/roles per servlet API: get("/foo", request.getRemoteUser == "admin") {...}

  • Use UI browser at http://swagger.wordnik.com/

  • Add API key support

  • Make the API actually do something

  • Add auth support - see example http://petstore.swagger.wordnik.com/api/api-docs