This page
Other pages
|
Key
This line was removed.
This word was removed. This word was added.
This line was added.
|
Changes (29)
View page history| h3. Examples of FAI data API |
| An API is an [Application Programming Interface|http://en.wikipedia.org/wiki/Application_programming_interface]. All sorts of people need FAI data and it should be delivered in a consistent form. *FAI needs an API*! |
| |
| Very This is a very simple example of the sort of data FAI should make available for people to use in their applications. |
| Select items below to include that data in the resulting RESTful XML data output, then press *get XML*. In MSIE the data should be displayed as XML, in Firefox you may have to look at the page source to see the XML data structure. To return to this page, simply press the back button. |
| |
| Select items below to include that data in the resulting XML data output, then press *get XML*. |
| |
| After you have pressed the button you can see the requested parameters in the URL. This URL can be used from anywhere to retrieve this data. |
| You are required to login, use 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. |
| |
| In a web browser this data is presented in a tree-like structure, that is what XML is. You can use the little - and + icons on the left side to collapse and expand different elements in the tree. To return to this page, simply press the back button. |
| {html} |
| <form method="get" action="http://www.flymicro.com/faidata/index.cfm"> |
| <form method="GET" action="https://www.flymicro.com/faidata/index.cfm"> |
| <b>General stuff</b><br /> <input type="checkbox" name="data" value="members.all"> List of FAI members (not guaranteed to be correct)<br/> |
... |
| {html} |
| h3. More from this API The key to this API is what is in the URL *after the ?* The examples above are just a small subset of what is available from an API like this, for example records for all microlight and paramotor classes are available, eg [?data=cima.records.PL1E|http://www.flymicro.com/faidata/index.cfm?data=cima.records.PL1E] will get you class PL1E. |
| see the [API Reference|API reference] for full syntax. This includes making it pretty with xsl stylesheets, for example[?data=members.america&xsl=1|https://www.flymicro.com/faidata/index.cfm?data=members.america&xsl=1] displays all FAI Members from the Americas in a user-friendly format. |
| |
| This API is also set up to get other subsets, for example [?data=cima.records.P|http://www.flymicro.com/faidata/index.cfm?data=cima.records.P] will get you all records in the paramotor classes or [?data=cima.records.1E|http://www.flymicro.com/faidata/index.cfm?data=cima.records.1E] will get you all records in electric classes flown solo. |
| h5. Making it useful Programmers know how to use XML data like this, but it can also be used directly by desktop programs like Excel. While raw XML can be imported into spreadsheets it is sometimes a little bit complicated, but importing transformed data is child's play with a web-query. * In excel 2003, open a new sheet. * menu: Data --> import external data --> new web query. * Put the URL in the address line (not forgetting the *&xsl=1* or *&xsl=2* to get the transformed version of the data) and press *Go*. * The page appears, select the range of data you want to import, where in the sheet you want to import it to, and click *import*. * Your data appears in the sheet. * To refresh the data, select a cell somewhere in the imported data and click menu: Data --> Refresh Data. |
| |
| You can do the same with the class list, as in [?data=cima.classes.P|http://www.flymicro.com/faidata/index.cfm?data=cima.classes.P] and [?data=cima.classes.1E|http://www.flymicro.com/faidata/index.cfm?data=cima.classes.1E] |
| h3. What this is What you have here is a simple [RESTful web service|http://en.wikipedia.org/wiki/Representational_State_Transfer] delivering read-only data (Technically, it is a GET). The data itself is presented in a pre-defined [xml|http://en.wikipedia.org/wiki/XML] format. |
| |
| With the keyword "all" you can get the lot, as in: [?data=cima.classes.all|http://www.flymicro.com/faidata/index.cfm?data=cima.classes.all] and [?data=cima.records.all|http://www.flymicro.com/faidata/index.cfm?data=cima.records.all] In this latter case it is quite a big data set which might take a bit of processing, hence the options above are probably more useful most of the time. |
| Security in this demo is at two levels: * Transport across the web is down a secure https 'tunnel'. * A login is required, but this can be *anonymous* for information already in the public domain. |
| |
| You can get two or more datasets simultaneously by concantenating them with ampersands: & as in: [?data=cima.records.WL1&data=cima.records.PL1E|http://www.flymicro.com/faidata/index.cfm?data=cima.records.WL1&data=cima.records.PL1E] |
| With API's like this it is also possible to send data the other way. (PUT or POST) or DELETE. These options are not currently implemented. |
| |
| h3. Members Purpose |
| With FAI members This API supports subsets by region, so [?data=members.europe|http://www.flymicro.com/faidata/index.cfm?data=members.europe] will get European FAI members. |
| The purpose of all this is just a simple demo to show the possibilities of the sort of data FAI should be making available, and a simple API to get it. |
| |
| 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|http://www.flymicro.com/faidata/index.cfm?data=members.south%20america] |
| *Several things will be noticed:* * No secure data is exposed to unauthenticated logins, eg email addresses. For this sort of thing a level of permissions is required. * There should however be a lot more info, eg NAC names Etc which is not contained in this demo database. * The primary objective of an API like this is data supply. It is not necessary for it to be able to deliver every possible query, for example the name of the NAC under which a World record was ratified, but it is necessary for it to deliver sufficient data that this could be determined from further processing. In this case the <fai_nation/> field would be used to join the two data sets. * Since an API like this is designed to be called often, it is a good idea to have subsets which are capable of delivering reasonably small amounts of data. No point in delivering all 500+ microlight records if only the ones for a single class are needed. * All data is encapsulated in a single <fai></fai> structure. While the whole purpose of this sort of thing is that it should be extensible, it would be very wise for FAI to create a basic structure which deals with the core data elements. The range of applications are vast, way more than this little demo and include sporting licences, competition entry lists, tracks, tasks, results... If all FAI associated data had a documented basic core structure then we are well on the way to having something *really useful*. * Standard format allows data to go in different directions with some confidence that it will be understood by the recipient - for example it becomes easy to load competition results in a common format to the FAI website Etc. * While it is recommended the <fai/> structure should be used to encapsulate everything possible, it should also be realized that there are some other formats commonly used for some things, eg [iCalendar|http://en.wikipedia.org/wiki/ICalendar] for calendars, [RSS|http://en.wikipedia.org/wiki/RSS] for news and [.igc|http://www.fai.org/gliding/system/files/tech_spec_gnss.pdf] for track files. * When structured data like this is available, people will start using it in ways FAI never imagined. Since the data we're talking about is all in the public domain already - it can only be a good thing for FAI. |
| |
| h3. CIMA Delegates As with FAI members, This API supports subsets by region for delegates, so [?data=cima.delegates.europe|http://www.flymicro.com/faidata/index.cfm?data=cima.delegates.europe] will get European CIMA Delegates |
| h3. Recommendation There are many opportunities for structured FAI data, but there is no structure. h5. It is strongly recommended a FAI wide Working Group is set up to establish this FAI structure. |
| |
| h3. Summary The purpose of the above is a simple demo to show the possibilities of the sort of data FAI should be making available. Several things will be noticed: * No secure data is exposed, eg email addresses. For this sort of thing a level of permissions is required. * There can however be a lot more info, eg NAC names Etc which is not contained in this demo database. * The objective of an API like this is data supply. It is not necessary for it to be able to deliver every possible query, for example the name of the NAC under which a World record was ratified, but it is necessary for it to deliver sufficient data that this could be determined from further processing. In this case the <fai_nation/> field would be used to join the two data sets. * It is a good idea to have subsets which are capable of delivering reasonably small amounts of data. No point in delivering all 500+ microlight records if only the ones for a single class are needed. * All data is encapsulated in a single <fai></fai> structure. While the whole purpose of this sort of thing is that it should be extensible, it would be very wise for FAI to create a basic structure which deals with the core data elements. The range of applications are vast, way more than this little demo and include sporting licences, competition entry lists, tracks, tasks, results... if all FAI associated data had a documented basic core structure then we are well on the way to having something *really* useful, and then data could start to go in different directions with some confidence that it will be understood by the recipient - for example it becomes easy to load competition results in a common format to the FAI website Etc. *It is strongly recommended a FAI wide committee is set up to establish this FAI structure*. |
| h3. Further reading |
| [web services|http://en.wikipedia.org/wiki/Web_service ] While this experimental API is not compliant, the [Atlassian REST API Design Guidelines|https://developer.atlassian.com/display/REST/Atlassian+REST+API+Design+Guidelines+version+1] is a very sensible approach to REST. |