Eric Berman edited this page Jun 16, 2018 · 13 revisions

MyFlightbook - Web

This project implements the MyFlightbook web server. This is where all the heavy lifting occurs - the database interaction, the business logic, account management, and the web service.

Setting up an instance of MyFlightbook

The Readme file (in the codebase) has instructions for how to set up an instance of the MyFlightbook server.

Web Service Functions (Mobile apps only)

MyFlightbook offers a wide variety of web services, exposed by SOAP. (Yeah, remember my rule - no laughing). This is used primarily by the mobile apps; if you have a website and would like to integrate with MyFlightbook, I would strongly prefer that you use oAuth (described below).

Here’s the flow for using the SOAP web service:

  1. Your app needs an app token that identifies your app. Contact me for an app token.
  2. The app collects the user’s email/password and calls AuthTokenForUser, or collects their information and calls CreateUser. An authtoken is returned; keep this secure and safe. Ideally, you do NOT store the email/password
  3. You can then use the authtoken directly to make calls (described below).

Interacting with MyFlightbook via oAuth 2.0

MyFlightbook supports oAuth 2.0. If you have a website and wish to integrate with MyFlightbook, you can create your own credentials.

The flow for oAuth is described below when MyFlightbook is the oAuth server. You can see it in action (with MyFlightbook as the client) if you go to MyFlightbook's website and go to Profile->Preferences and authorize either a social network or cloud storage provider like Dropbox.

  1. When your app is set up with oAuth, it is given an app ID and an app secret.
  2. The user clicks on a link in your app to authorize the app to talk to MyFlightbook.
  3. The user is redirected – via web browser – to MyFlightbook; the URL includes both your app’s ID and a known redirect URL, as well as requested “scopes” (i.e., what permissions it wants, such as “View and update flights, View totals”, etc.)
  4. MyFlightbook validates that the app ID is known AND that the redirect URL is a known location (to prevent spoofing)
  5. MyFlightbook requires the user to sign in (or create an account), if they aren’t already, thus authenticating themselves.
  6. MyFlightbook presents a page to the user asking if it’s OK to grant your app the requested scopes.
  7. If the user says “yes”, then they are redirected back to the calling website, along with an authorization token in the URL. This token is what says “[Username] has given permission for [App name] to access [User]'s account on MyFlightbook”, but it doesn’t quite yet let you make those calls. After all, since it’s passed in the URL, it can be seen and thus isn't secret. This token has a time limit on it.
  8. The website now takes that authorization token and makes a server-to-server call to MyFlightbook, passing its App ID AND it’s App Secret AND the authorization token from step 7. The App ID + secret prove to MyFlightbook that you really are the app you claim to be, and the authorization token proves that the user gave permission to your app. MyFlightbook then returns an actual access token, which can be used to make calls to the web service. This, obviously, needs to be safely and securely stored.
  9. The access token may be time limited (depends on the oAuth server), in which case steps 1-8 need to be periodically repeated.
  10. You can now hit the functional endpoints on MyFlightbook, passing the access token from step 8. Some can be GET, most would need to be POST; you’d JSON-encode the relevant parameters and the results come back in JSON format.

The URL for the actual calls is https://myflightbook.com/logbook/public/oAuthToken.aspx/{methodname}?access_token={token}&..., where "methodname" is the method being called (below) and {token} is the URL-encoded access token returned in step 8 above. I currently also support "json=1" as an additional URL parameter if you want the results in JSON format; otherwise, you will get XML. If you request JSON and also provide a "callback=..." parameter with a non-empty name, then I will return JSONP. You can POST or GET, but due to URL length limitations, Posting is generally preferred.

Note: JSON results sometimes include more data than XML due to the way the Newtonsoft engine serializes objects. However, if the field is NOT present in the WSDL, then it is NOT supported and may disappear at any time.

There is a a web page on the site that goes through all of the above to verify the oAuth process and includes user interface to make many of the calls described below.

Available web service functions:

The list of calls is described here, and the detailed description (WSDL, or "Web Service Description Language") of supported calls is here; note that only the calls described below are supported (the remainder are deprecated and may disappear over time).

If you are using oAuth, these are accessed via GET or POST using JSON encoded values to send/receive data; if using SOAP, this is all XML.

Also, if you are using oAuth, each call requires an oAuth "scope" to be granted in order to use it. The SOAP API does not use scopes; as a result, all calls are available via SOAP.

In the summary below, I denote each call by the common CRUD acronym role - Create, Read, Update, Deleete.

Aircraft

  • C - AddAircraftForUser (Scope: addaircraft) – adds an aircraft to the user’s account
  • R - AircraftForUser – (Scope: readaircraft) returns a list of the aircraft that the user has in their account
  • R – MakesAndModels – (Scope: readaircraft) returns a list of the models of aircraft in the system (necessary in order to create an aircraft)
  • U - UpdateMaintenanceForAircraftWithFlagsAndNotes – (Scope: addaircraft) updates an aircraft (you can’t modify the aircraft per se from the app, you can only update maintenance, modify flags, or add/update notes.
  • D - DeleteAircraftForUser – (Scope: addaircraft) removes an aircraft from the user’s account

Flights

  • C/U – CommitFlightWithOptions – (Scope: addflight) adds or updates a flight (the FlightID determines if it’s an add or update operation. FlightID < 0 = new.)
  • R – FlightsWithQueryAndOffset – (Scope: readflight) retrieves a specified number of flights, offset by a given offset. E.g., “give me 30 flights starting at position 61”. This lets you do things like infinite scroll
  • R – FlightPathForFlight, FlightPathForFlightGPX – (Scope: readflight) returns the path of the flight (if present)
  • R – PropertiesForFlight – (Scope: readflight) returns the additional flight properties associated with a flight (not present by default in FlightsWithQueryAndOffset)
  • R – AvailablePropertyTypesForUser – (Scope: readflight) returns the set of possible property types for this user; denotes which ones have been previously used by the user, and previous values for text values (e.g., student name) as well.
  • D – DeleteLogbookEntry – (Scope: addflight) Deletes a flight
  • D – DeletePropertiesForFlight – (Scope: addflight) doesn’t delete the flight, but removes one or more properties from it.

Currency

  • R – GetCurrencyForUser – (Scope: currency) Returns the user’s currency

Totals

  • R –TotalsForUserWithQuery – (Scope: totals) returns totals for the user. You can pass a query indicating which flights to include.

Visited Airports

  • R – VisitedAirports - (Scope: visited) Returns a list of airports that the user has recorded in their flights.

Images (flight or aircraft):

  • C – Not done through the web service; these are done at http://myflightbook.com/logbook/public/uploadpicture.aspx for flight images or UploadAirplanePicture.aspx for aircraft images. These are POSTs to the respective page and must be secure. They must include the following form parameters:

    • "txtAuthToken" - the authtoken (oAuth or webservice) authorizing the upload
    • "imgPicture" - the bytes of the image. MUST include the MIME content-type
    • "txtComment" - the comment for the image (optional)
    • "txtLat"/"txtLon" - the latitude/longitude (flights only, optional, using US formatting)
    • "idFlight" - the id of the flight (if a flight image); must be owned by the user authorized by the authtoken
    • "txtAircraft" - the id of the aircraft (if an aircraft image); must be in the list of aircraft for the user.
  • R – Not done through the web service; references to the images are include in the flights or aircraft themselves

  • U – UpdateImageAnnotation – (Scope: images) updates the comment for an image.

  • D – DeleteImage – (Scope: images) deletes an image for a flight or aircraft.

Named Queries

  • C/U - AddNamedQueryForUser (Scope: namedqueries) - Adds or updates a query for the specified user with a given name.
  • R - GetNamedQueriesForUser (Scope: namedqueries) - Retrieves the stored queries for the specified user
  • D - DeleteNamedQueryForUser (Scope: namedqueries) - Deletes the query for the specified users

There are others, but they are either deprecated or used internally; DO NOT RELY ON THEM.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.