Access Keys:
Skip to content (Access Key - 0)
All CIMA spaces

CIMA

This space

API reference

Security

The API requires a login, either:

  • username: anonymous password : blank
  • For enhanced data, use your wiki login credentials. What enhanced data is supplied depends on what groups you are a member of in the wiki.

Authentication is standard HTTP basic, in other words the username and password are not encrypted, but the API is set up to only work with SSL/TLS on the standard https port 443 so all communication with the API is done from end to end down a very secure encrypted 'tunnel'.

Query parameters

Parameters describing the data you want to receive are sent to the API in the form of a GET, in other words it is a page request like any other page request on the internet and the URL contains the requested parameters after the ? and this is known as the query. POST requests, in other words form submissions, are not currently supported.

Query parameters can be concantenated with ampersands &, as in URI?data=return.this.data&data=return.that.data.too

It does not matter what order query parameters are in; URI?data=return.this.data&data=return.that.data.too will return the same data in the same order as URI?data=return.that.data.too&data=return.this.data.

Query parameters should be properly URL encoded, so the value you need to find FAI members in South America, (which has a space in it), should be: ?data=members.south%20america

Query parameter Required  
data yes The basic parameter which defines what data to retrieve.
Values

The value is in dot notation, thus a typical url will look like URI?data=return.this.data

The dot notated value is in the form path.optional_path.dataset. and is a reflection of the eventual XML structure.  fai is assumed, and thus omitted.  a typical query would be ?data=members.all or data=cima.delegates.all  For subsets, see the reference below.

Requests for multiple simultaneous datasets are supported, concantenated with ampersands &, as in URI?data=return.this.data&data=return.that.data.too will load both datasets into the resulting xml structure.

Example

 ?data=members.all&data=cima.delegates.all gets FAI members and CIMA delegates simultaneously.

xsl no Loads a XSLT stylesheet with the XML data so it is nicely presented in a browser. (do not confuse this parameter with xls).
Values

1 : Loads selected requested data nicely formatted in sortable tables.
2 : Loads all the requested data in generic tables.  Useful for things like web-queries in Excel.

Other values are ignored. 

Example

?data=members.all&xsl=1

logout no Forces a logout. 
Values

1 : Logs the current user out and the login dialog appears.
anything else : the logout parameter is ignored.

Only useful if the user is viewing the data in a browser and wants to change login credentials. 

If data is being retrieved by machine then login credentials are not stored between requests and are therefore required every time.  if the logout parameter is used in such requests then the effect will be to log the request in, and then immediately out and the resulting response status code will be 401 Unauthorized

Example

?data=members.all&logout=1

The XML structure

All data returned in a single request is always contained within a single <fai> </fai> structure.  This allows consistency within applications using the data.

For simplicity, the schema is laid out so only nodes which can contain sub-nodes have attributes (eg itemcount)

What is contained within the <fai/> structure depends on the request, but (consistent with the available data) can be:

<fai copyright="FAI" href="http://www.fai.org" timestamp="iso timestamp, always UTC" user="person who is logged in" version="current ver.">
    <members itemcount="number of member items" validity="a comment on validity (optional)">
       <member/>....
    </members>
    <cima>
      <classes itemcount = "number of class items">
        <class/>....
      </classes>
      <delegates itemcount = "number of delegate items" validity="a comment on validity (optional)">
        <delegate/>....
      </delegates>
      <records itemcount = "number of record items">
        <record/>....
      </records>
    </cima>
</fai>
<members/> 

FAI member nations

Method GET
Query string data=members.dataset
Dataset all or any region, eg Europe, Asia, America Etc.
Notes Only subsets of FAI members by continent are supported, so ?data=members.europe will get European FAI members. It will also do partial matches, so ?data=members.asia will retrieve members from East Asia and South Asia.

Note that in all cases the URL must be properly encoded, so the url for South America, which has a space in it, should be:
?data=members.south%20america
<classes/>

FAI commission aircraft classes

Method GET
Query string data=commission.classes.dataset
Dataset all or any part of the class name eg P or PL or PL1 Etc.
Notes Data is only available for CIMA

The subset must be a contiguous part of the class name, thus ?data=cima.classes.P1 will return nothing whereas ?data=cima.classes.L1 will return all classes which are Landplanes flown solo.
<delegates/>

FAI commission delegates

Method GET
Query string data=commission.delegates.dataset
Dataset all or any region, eg Europe, Asia, America Etc.
Notes Data is only available for CIMA

Only subsets of delegates by continent are supported, so ?data=cima.delegates.europe will get European CIMA delegates. It will also do partial matches, so ?data=cima.delegates.asia will retrieve CIMA delegates from Central, East and South Asia
<records/>

FAI records

Method GET
Query string data=commission.records.dataset
Dataset all or any part of the class name eg P or PL or PL1 Etc.
Notes Data is only available for CIMA

The subset must be a contiguous part of the class name, thus ?data=cima.records.P1 will return nothing whereas ?data=cima.records.L1 will return all records ratified in Landplanes flown solo.

To get two or more classes simply concantenate the request; ?data=cima.records.PL1&data=cima.records.PL2 will retrieve records for classes PL1 and PL2. 

The all dataset is rather large and not recommended.

Errors

There are essentially two types of error:

  • Page status errors.
    • If a dataset is served correctly the recipient will receive a normal 200 OK status code.
    • The most likely alternative status code will be 401 Unauthorized indicating the login is incorrect or has timed out.
  • Data production errors
    • These are output within the XML structure <error/> and attempt to describe the problem.

Added by Richard Meredith-Hardy Last edited by Richard Meredith-Hardy on 14 May, 2012 10:25. Quick links: http://wiki.fai.org/x/AgBz or API reference
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
Adaptavist Theme Builder Powered by Atlassian Confluence