InTRePId 7
Title: An HTTP API for Data Export
Author: Pedro Ferreira, Adrian Mönnich
Date: April 2011
Target version: v0.98
Status: implemented
Objectives
- Creating a centralized data access API for Indico;
- Replacing the existing export scripts (export.py...) with something more usable and possibly more efficient;
- Enabling the quick implementation of export capabilities for different data formats;
- Allowing access to protected information, through the use of some authentication mechanism;
- Introducing some kind of control/logging mechanism that allows us to know who is using what and how often;
- Introducing defense mechanisms against abusive uses of the API;
- Creating extension points that allow different plugins to use this mechanism and add their own data;
Status quo
Currently, a series of scripts are used in order to provide data from Indico in different formats:
- export.py - enables access to HTML, XML, RSS and iCal listings of events contained in specific categories and following specific date spans;
- exportReservations.py - provides XML and CSV lists of reservations between a specified date span;
- RSS/iCal interfaces - same as export.py (for the corresponding formats), with the addition that they apply only to upcoming events, and that the iCal interface can also export the components of an event (contributions);
- XML Gateway - provides information about webcasts;
Description
Requirements
- A basic "as REST as possible" HTTP API for data export;
- An easy to use, flexible and intuitive query URL syntax;
- Support for different data formats;
- XML
- JSON/JSONP
- HTML 4 snippets (with proper CSS classes);
- RSS
- iCal
- CSV ?
- HTML 5 with CSS and microdata ?
- YAML ?
- RDF ?
- A safe and easy to use authentication mechanism;
- HTTPS support (HTTPS only?);
- Reasonable load on Indico/DB, obtained among others through caching of results;
- Support for an "API key" kind of mechanism, including a list of authorized users/keys and their access level as well as some access statistics;
- Timezone support - both for querying and display of results;
Specification details
Date and time formats
The user should be able to specify dates and times in both an absolute and a relative way:
- Using a subset of ISO8601;
- Using the keywords yesterday, today, now, tomorrow. now would be the current date/time while the others would change value according to their context:
- Date of the day in question, 00:00, if specified as from;
- Date of the day in question, 23:59 if specified as to;
- Using a relative notation like 5d, -1h, 2d1h30m, etc...
If not specified, date and time parameters should extend to minus or plus infinity.
Time zone support
Some details about timezone support:
- API users should be able to specify a timezone in which the results should be displayed; Otherwise, results should be displayed in their original timezones;
- If a user specifies a timezone (previous point), the API should consider that all other parameters (start date, etc...) are in the same timezone.
Authentication
Users should be able to request API keys from their profile pages. These API keys will grant whoever uses them equal rights to the user in terms of data access. There should be as well an encryption key, a shared secret that should be used to sign the request (ordered list of parameters), and that will guarantee that no-one has simply stolen the API key and used it to produce their own request.
signature = sha1(ordered_query_string + enc_key)
HTTPS support should be available, thus guaranteeing a secure communication channel.
Examples
[ { id: 1234, title: "An event", datetime: { date: "2011-03-01", time: "20:00" } } ]
Comments
