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.

In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:

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.

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.

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.

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.

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.

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.