LogTen Pro API. logten://method/{json_payload}

Transcription

1 LogTen Pro API proudly presents the LogTen Pro Application Programming Interface (API) v1.1 which allows third-party applications to interact with LogTen Pro using a straight forward URL based approach using JSON (JavaScript Object Notation). The LogTen Pro API v1.1 is available starting with the following versions of the software: LogTen Pro Mac v5.7.0 LogTen Pro iphone v3.2.0 LogTen Pro ipad v1.2.0 LogTen Pro is registered to handle requests to the logten:// URI scheme. Any requests made to the logten:// scheme will be passed off to LogTen Pro for handling. The general format of the request is as follows: logten://method/{json_payload} The json_payload shall always contain a metadata dictionary. The metadata dictionary must always contain the requesting application name as well as the requesting applicationʼs version information. Depending on the actual method invoked, the metadata may contain optional parameters. logten://method/{"metadata":{"application":"my Application", "version":"1.0", "optional_parameter":"some_value"},...} Notes: 1. You must be sure to escape any special JSON characters in your JSON payload to ensure proper parsing by LogTen Pro. If any of your values contains a single quote, double quote or a backslash, you will need to prepend a backslash to that character in the payload. For instance if your value was " My data contains a \ and a. it would become " My data contains a \\ and a \. 2. The complete URL should have any characters escaped that are not legal URL characters (based on RFC 2396). In Cocoa, this can easily be accomplished by running the NSʼs - (NS *) stringbyaddingpercentescapesusingencoding: (NSEncoding)encoding method on the URL string with the NSUTF8Encoding encoding. Identifying flights LogTen Pro utilizes the flight_key attribute on the flight entity to uniquely identify flights provided from an external source. The flight_key attribute is a string value and is required to be unique for a given logbook. When a flight record is sent through the API that includes a flight_key, LogTen Pro will first attempt to locate a matching flight with that flight_key. If a create or modify operation is being run and a matching flight already exists with that flight_key, that flight will be modified with the provided data. If a matching flight is not found, a new one will be created with the provided data. For removal operations, only flights with the matching flight_key will be removed. Please note: If the matching flight is locked (flight_islocked is set to 1), the flight will not be modified or deleted. - LogTen Pro API v1.1-7/15/11 1

2 v1.1 Supported Methods addflights The addflights method allows a third-party application to create/modify flights within the LogTen Pro logbook. When the addflights method is invoked, LogTen Pro will ask the user if they wish to create/modify the flights from the requesting application. The addflights method expects the metadata dictionary and a collection of flights. logten://addflights/{"metadata":{"application":"my App", "version":"1.0",...}, "flights":[{flight1 info...}, {flight2 info...},...]} metadata: The addflights method allows three optional parameters in the metadata dictionary: dateformat - The dateformat parameter specifies how date values should be parsed when they are passed in as string values. The date format string uses the format patterns recognized by the NSDateFormatter class (i.e. MM/dd/yyyy ). dateandtimeformat - The dateandtimeformat parameter specifies how date values should be parsed when they are passed in as string values. The date and time format string uses the format patterns recognized by the NSDateFormatter class (i.e. MM/dd/yyyy HH:mm ). timesarezulu - The timesarezulu parameter specifies whether any passed in string time values are in Zulu time or should be converted to local time based on the time zone of the departure or arrival airports. Valid values for the timesarezulu parameter are true or false. If this parameter is not supplied, the default value is true. flights: The flights collection shall contain the flight information for each flight to be created/ modified. If a flight_key value is provided for a given flight, LogTen Pro will first attempt to locate a flight in the logbook matching the flight_key. If a matching flight is found, that flight will be updated with the provided attributes. If a matching flight is not found, a new flight will be created. Any of the valid LogTen Pro flight attributes are available for use (see Appendix for the current, complete list of relevant flight attributes). The addflights method will allow flight time values to be supplied as either the decimal number of hours (i.e. 1.5), the number of hours and minutes separated by a colon (i.e. 1:30 ) or the number of hours and minutes separated by a plus sign (i.e ). The addflights method will allow date values to be supplied as either a string value that matches the dateformat parameter supplied in the metadata or as the number of seconds from the unix epoch (this value can be returned using the NSDate timeintervalsince1970 method in Cocoa). The addflights method will allow date/time values to be to be supplied as either a string value that matches the dateandtimeformat parameter supplied in the metadata or as the number of seconds from the unix epoch (this value can be returned using the NSDate timeintervalsince1970 method in Cocoa). The timesarezulu parameter is only - LogTen Pro API v1.1-7/15/11 2

3 applicable to date/time values that are passed in as strings. When handling local times, the addflights method will first attempt to obtain the time zone for the applicable to or from place (depending on the attribute being set). If there is no corresponding place or it does not have a time zone associated with it, the addflights method will attempt to use the default timezone set for LogTen Pro. If there is no default timezone configured, the addflights method will use GMT. The following is an example of a valid addflights request: logten://addflights/{"metadata":{"application":"my Application", "version":"1.0", "dateformat":"mm/dd/yyyy", "dateandtimeformat":"mm/dd/yyyy HH:mm", "timesarezulu":"true"}, "flights":[{"flight_flightdate":"12/25/2010", "flight_to": "KPIT", "flight_from":"kpjc", "flight_pic":"1:30", "flight_takeofftime":"12/25/ :50"}]} modifyflights The modifyflights method allows a third-party application to create, modify and remove flights within the LogTen Pro logbook. When the modifyflights method is invoked, LogTen Pro will ask the user if they wish to create/modify and remove the flights from the requesting application. The modifyflights method expects the metadata dictionary, a collection of flights to create/modify and collection of flights to remove. The modifyflights method requires at least both collections to be present, however it is valid to send empty collections. logten://modifyflights/{"metadata":{"application":"my App", "version":"1.0",...}, "flights":[{flight1 info...}, {flight2 info...},...], "removeflights":[{flight1 flight_key}, {flight2 flight_key},...]} metadata: The modifyflights method allows three optional parameters in the metadata dictionary: dateformat - The dateformat parameter specifies how date values should be parsed when they are passed in as string values. The date format string uses the format patterns recognized by the NSDateFormatter class (i.e. MM/dd/yyyy ). dateandtimeformat - The dateandtimeformat parameter specifies how date values should be parsed when they are passed in as string values. The date and time format string uses the format patterns recognized by the NSDateFormatter class (i.e. MM/dd/yyyy HH:mm ). timesarezulu - The timesarezulu parameter specifies whether any passed in string time values are in Zulu time or should be converted to local time based on the time zone of the departure or arrival airports. Valid values for the timesarezulu parameter are true or false. If this parameter is not supplied, the default value is true. flights: The flights collection shall contain the flight information for each flight to be created/ modified. If a flight_key value is provided for a given flight, LogTen Pro will first attempt to locate a flight in the logbook matching the flight_key. If a matching flight is found, that flight will be updated with the provided attributes. If a matching flight is not found, a new - LogTen Pro API v1.1-7/15/11 3

4 flight will be created. Any of the valid LogTen Pro flight attributes are available for use (see Appendix for the current, complete list of relevant flight attributes). The modifyflights method will allow flight time values to be supplied as either the decimal number of hours (i.e. 1.5), the number of hours and minutes separated by a colon (i.e. 1:30 ) or the number of hours and minutes separated by a plus sign (i.e ). The modifyflights method will allow date values to be supplied as either a string value that matches the dateformat parameter supplied in the metadata or as the number of seconds from the unix epoch (this value can be returned using the NSDate timeintervalsince1970 method in Cocoa). The modifyflights method will allow date/time values to be to be supplied as either a string value that matches the dateandtimeformat parameter supplied in the metadata or as the number of seconds from the unix epoch (this value can be returned using the NSDate timeintervalsince1970 method in Cocoa). The timesarezulu parameter is only applicable to date/time values that are passed in as strings. When handling local times, the modifyflights method will first attempt to obtain the time zone for the applicable to or from place (depending on the attribute being set). If there is no corresponding place or it does not have a time zone associated with it, the modifyflights method will attempt to use the default timezone set for LogTen Pro. If there is no default timezone configured, the modifyflights method will use GMT. removeflights: The removeflights collection shall contain the flight_key for each flight to be removed. The following is an example of a valid modifyflights request: logten://modifyflights/{"metadata":{"application":"my Application", "version":"1.0", "dateformat":"mm/dd/yyyy", "dateandtimeformat":"mm/dd/yyyy HH:mm", "timesarezulu":"true"}, "flights":[{"flight_key":"myappflight_101", "flight_flightdate":"12/25/2010", "flight_to": "KPIT", "flight_from":"kpjc", "flight_pic":"1:30", "flight_takeofftime":"12/25/ :50"}], "removeflights": [{"flight_key":"myappflight_101"}, {"flight_key":"myappflight_102"}]} - LogTen Pro API v1.1-7/15/11 4

5 Appendix: Valid attributes Flights General Attributes: flight_key Uniquely identifies a flight created from an external source flight_cloudbase flight_customnote1 flight_customnote2 flight_customnote3 flight_customnote4 flight_customnote5 flight_distance flight_dutytimepayrate flight_expenses flight_flagged 0 or 1 flight_flight flight_flighttimepayrate flight_fuelburned flight_hobbsstart flight_hobbsstop flight_instrumentproficiencycheck 0 or 1 flight_islocked 0 or 1 flight_leg flight_nightvisionsystem flight_payload flight_remarks flight_review 0 or 1 flight_scheduledtimepayrate - LogTen Pro API v1.1-7/15/11 5

6 flight_sky flight_tachstart flight_tachstop flight_totalearned flight_visibility flight_weather flight_winddirection flight_windvelocity Dates and Times: flight_actualarrivaltime flight_actualdeparturetime flight_flightdate flight_landingtime flight_offdutytime flight_ondutytime flight_scheduledarrivaltime flight_scheduleddeparturetime flight_takeofftime Flight Times: flight_actualinstrument flight_aircraftclass1 flight_aircraftclass2 flight_aircraftclass3 flight_aircraftclass4 flight_aircraftclass5 - LogTen Pro API v1.1-7/15/11 6

7 flight_aircraftclass6 flight_aircraftclass7 flight_aircraftclass8 flight_aircraftclass9 flight_aircraftclass10 flight_aircraftclass11 flight_aircraftclass12 flight_aircraftclass13 flight_aircraftclass14 flight_aircraftclass15 flight_category1 flight_category2 flight_category3 flight_category4 flight_category5 flight_category6 flight_category7 flight_category8 flight_category9 flight_category10 flight_category11 flight_category12 flight_category13 flight_category14 flight_category15 flight_commandpractice flight_crosscountry flight_customtime1 - LogTen Pro API v1.1-7/15/11 7

8 flight_customtime2 flight_customtime3 flight_customtime4 flight_customtime5 flight_customtime6 flight_customtime7 flight_customtime8 flight_customtime9 flight_customtime10 flight_customtime11 flight_customtime12 flight_customtime13 flight_customtime14 flight_customtime15 flight_customtime16 flight_customtime17 flight_customtime18 flight_customtime19 flight_customtime20 flight_dualgiven flight_dualreceived flight_dualreceivednight flight_duration flight_enginetype1 flight_enginetype2 flight_enginetype3 flight_enginetype4 flight_enginetype5 - LogTen Pro API v1.1-7/15/11 8

9 flight_enginetype6 flight_enginetype7 flight_enginetype8 flight_enginetype9 flight_enginetype10 flight_enginetype11 flight_enginetype12 flight_enginetype13 flight_enginetype14 flight_enginetype15 flight_flightengineer flight_ground flight_multipilot flight_night flight_nightvisiongoggle flight_p1us flight_p1usnight flight_pic flight_picnight flight_relief flight_scheduledtotaltime flight_sfi flight_sic flight_sicnight flight_simulatedinstrument flight_simulator flight_solo flight_totaldutytime - LogTen Pro API v1.1-7/15/11 9

10 flight_totalinstrument flight_totaltime Takeoffs: flight_customtakeoff1 flight_customtakeoff2 flight_customtakeoff3 flight_customtakeoff4 flight_customtakeoff5 flight_customtakeoff6 flight_customtakeoff7 flight_customtakeoff8 flight_customtakeoff9 flight_customtakeoff10 flight_daytakeoffs flight_nighttakeoffs flight_nightvisiongoggletakeoffs flight_shipboardtakeoffs flight_totaltakeoffs flight_watertakeoffs Landings: flight_customlanding1 flight_customlanding2 flight_customlanding3 flight_customlanding4 flight_customlanding5 - LogTen Pro API v1.1-7/15/11 1

11 flight_customlanding6 flight_customlanding7 flight_customlanding8 flight_customlanding9 flight_customlanding10 flight_daylandings flight_nightlandings flight_nightvisiongogglelandings flight_shipboardlandings flight_totallandings flight_waterlandings Misc Takeoff/Landing: flight_arrests flight_autolands flight_bolters flight_catapults flight_fcls flight_fullstops flight_touchandgoes Operations: flight_aerotows flight_approachplace flight_approachtype flight_catii flight_catiii - LogTen Pro API v1.1-7/15/11 11

12 flight_customop1 flight_customop2 flight_customop3 flight_customop4 flight_customop5 flight_customop6 flight_customop7 flight_customop8 flight_customop9 flight_customop10 flight_goarounds flight_groundlaunches flight_holds flight_poweredlaunches flight_totalapproaches Capacities: flight_customcapacity1 0 or 1 flight_customcapacity2 0 or 1 flight_customcapacity3 0 or 1 flight_customcapacity4 0 or 1 flight_customcapacity5 0 or 1 flight_customcapacity6 0 or 1 flight_customcapacity7 0 or 1 flight_customcapacity8 0 or 1 flight_customcapacity9 0 or 1 flight_customcapacity10 0 or 1 flight_faapart61 0 or 1 - LogTen Pro API v1.1-7/15/11 12

13 flight_faapart91 0 or 1 flight_faapart121 0 or 1 flight_faapart135 0 or 1 flight_far1 0 or 1 flight_flightengineercapacity 0 or 1 flight_landingcapacity 0 or 1 flight_piccapacity 0 or 1 flight_pilotflyingcapacity 0 or 1 flight_reliefcrewcapacity 0 or 1 flight_siccapacity 0 or 1 flight_undersupervisioncapacity 0 or 1 Aircraft: flight_selectedaircraftclass flight_selectedaircraftid flight_selectedaircrafttype flight_selectedcategory flight_selectedenginetype flight_selectedmake flight_selectedmodel Crew: flight_selectedcrewcommander flight_selectedcrewcustom1 flight_selectedcrewcustom2 flight_selectedcrewcustom3 flight_selectedcrewcustom4 - LogTen Pro API v1.1-7/15/11 13

14 flight_selectedcrewcustom5 flight_selectedcrewflightattendant flight_selectedcrewflightattendant2 flight_selectedcrewflightattendant3 flight_selectedcrewflightattendant4 flight_selectedcrewflightengineer flight_selectedcrewinstructor flight_selectedcrewobserver flight_selectedcrewobserver2 flight_selectedcrewpic flight_selectedcrewpicid flight_selectedcrewpurser flight_selectedcrewrelief flight_selectedcrewrelief2 flight_selectedcrewrelief3 flight_selectedcrewrelief4 flight_selectedcrewsic flight_selectedcrewsicid flight_selectedcrewstudent Place: flight_from flight_fromcity flight_fromcountry flight_fromstate flight_route flight_to flight_tocity - LogTen Pro API v1.1-7/15/11 14

15 flight_tocountry flight_tostate - LogTen Pro API v1.1-7/15/11 15