View Source

h3. 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'.

h3. 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|https://www.flymicro.com/faidata/index.cfm?data=members.south%20america]

|| Query parameter || Required || ||
| data | yes | The basic parameter which defines what data to retrieve.
h6. 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.
h6. Example
 [?data=members.all&data=cima.delegates.all|https://www.flymicro.com/faidata/index.cfm?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).
h6. 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. 
h6. Example
[?data=members.all&xsl=1|https://www.flymicro.com/faidata/index.cfm?data=members.all&xsl=1] |
| logout | no | Forces a logout. 
h6. 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* \\
h6. Example
[?data=members.all&logout=1|https://www.flymicro.com/faidata/index.cfm?data=members.all&logout=1]\\
\\ |

h3. The XML structure

All data returned in a single request is&nbsp;always contained within a single&nbsp;<fai> </fai> structure.&nbsp; This&nbsp;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:

{code:xml}
<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>
{code}

h5. <members/>&nbsp;

*FAI member nations*
| Method | GET |
| Query string | data=members._dataset_ |
| Dataset | *all* or any region, eg Europe, Asia, America Etc. |
| Notes | Only&nbsp;subsets of FAI members by continent are supported, so [?data=members.europe|https://www.flymicro.com/faidata/index.cfm?data=members.europe] will get European FAI members. It will also do partial matches, so [?data=members.asia|https://www.flymicro.com/faidata/index.cfm?data=members.asia] will retrieve&nbsp;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|https://www.flymicro.com/faidata/index.cfm?data=members.south%20america] |

h5. <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|https://www.flymicro.com/faidata/index.cfm?data=cima.classes.P1] will return nothing whereas [?data=cima.classes.L1|https://www.flymicro.com/faidata/index.cfm?data=cima.classes.L1] will return all classes which are Landplanes flown solo. |

h5. <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&nbsp;subsets of delegates by continent are supported, so [?data=cima.delegates.europe|https://www.flymicro.com/faidata/index.cfm?data=cima.delegates.europe] will get European CIMA delegates. It will also do partial matches, so [?data=cima.delegates.asia|https://www.flymicro.com/faidata/index.cfm?data=cima.delegates.asia] will retrieve CIMA delegates from Central, East and South Asia |

h5. <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|https://www.flymicro.com/faidata/index.cfm?data=cima.records.P1] will return nothing whereas [?data=cima.records.L1|https://www.flymicro.com/faidata/index.cfm?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|https://www.flymicro.com/faidata/index.cfm?data=cima.records.PL1&data=cima.records.PL2] will retrieve records for classes PL1 and PL2.&nbsp; \\ \\
The *all* dataset is rather large and not recommended. |

h3. 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.