The Flashcard Exchange API provides a simple
RESTful
interface with lightweight
JSON-formatted responses to use
many of the Flashcard Exchange website features. This document provides information to developers on
how to integrate with the Flashcard Exchange API.
The Flashcard Exchange API requires an application key that is provided during registration.
The key identifies your application to the Flashcard Exchange web service, and
is used to track overall call usage.
It's passed using the standard
api_key parameter. Email
support@flashcardexchange.com to request a key for your application. You will also be given oauth key and secret values for accessing protected user data according to our
oauth authentication server.
The Flashcard Exchange API uses a RESTful calling style that works with standard HTTP calls.
Any web programming language (PHP, Ruby, Perl, Python, Java, Objective C,
C#...) should be able to make and receive HTTP networking calls;
consult the documentation for your language of choice.
Request URLs
In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:
http://api.flashcardexchange.com/v1/get_tag?tag=math&api_key=CuGEqR171v&page=1&indent=2&sort=date
The prefix v1 is the version specifier and must be present. When significant
changes are made to the API (changes that would break compatibility with
existing applications) this value will change.
Authentication
We provide an
oauth authentication service for
accessing protected user data. This type of user authentication is required
for accessing private data and for sending data updates back into the system.
If you just want to provide read only access for your users you only need to
authenticate your application with the api_key parameter but users will not be
able to view their private data.
Request Methods
- Request methods are detailed in the api methods document.
Output Format
Currently, the only supported formats are JSON and JSON with padding. The
default output format is JSON. If you want padding include a HTTP GET
parameter indent. This parameter must be an integer and will be used
as the indentation value.
JSON Data
Data is returned using JSON, a lightweight serialization language that is
compatible with many different languages. JSON is also syntactically correct
JavaScript code, which means that it can be parsed with JavaScript's own eval()
function.
Standard Response Format
Each API response is wrapped in a standard structure that holds the results of the API call, plus metadata about the request:
{
"response_type": "ok",
"results": { result object }
"parameters": {
"q": "math",
"indent": 2,
"page": 1
}
}
response_type specifies the type of response and will contain either "ok" or "error"
results is an array of results. For consistency's sake, it is always an array, even if only one result is expected.
parameters echoes the parameters that were passed in the request.
Errors
response_type will be set to "error" if a problem is encountered. The results object will contain two elements, one for error_number and another for error_message. An example error document is below.
{
"response_type": "error",
"results": {
"error_number": "3",
"error_message": "Unknown developer key."
},
"parameters": {
"q": "math",
"application": "CuGEqR171v",
"indent": "2",
"page": "1"
}
}
Include a
lang parameter to any request to return the error codes in a
different language. Please contact
support if you are
using this feature-- not all error codes have been translated into all
languages.
Abuse or misuse of the api will be handled on a case by case basis. We reserve
the right to refuse API access to your applications if we are uncomfortable
with the way you are using it. We informally request that you clearly indicate
that the data is originating from www.flashcardexchange.com. We also ask that
you do not download and store data in another server repository. We provide
this API service free of charge in the hopes that more people will become aware
of Flashcard Exchange. Please help us achieve this goal.
Copyright © 2001-2012 Collective Research