Data API: Introduction

Freecode data API

Disclaimer: The API and its documentation are still fairly new. Commands and attributes should be feature complete. There may still be errors in the documentation or the implementation that will be ironed out. Changes to existing methods or attributes as well as new methods and attributes will be properly highlighted when those changes are introduced. If you have problems, open a new discussion in the API forum

Intro

Freecode implements a RESTful API based on either JSON or XML inputs. There is no functionality difference between either format.

All write requests submitted via the API are subject to moderation by the Freecode staff similar to the procedure required for data submitted through the regular web interface.

This API deals with data gathering and data entry for the following data types:

Except for projects, each of the data types is based off of a project that it deals with. This is reflected in the URI that is used to access or write those data types.

Example implementation

Eric S. Raymond maintains freecode-submit, which, starting from version 2.0, is fully API compatible to the new Freecode data API. freecode-submit is written in Python and can serve as an implementation example for other programmers.

Attribute types

  • Integer
  • String - 255 characters maximum, no HTML, subject to filtering
  • Text - 65535 characters maximum, no HTML, subject to filtering
  • Datetime - Datetime string in UTC, generally read-only

Attributes declared as URI Identifier will be used to access the data type via URIs.

A word on URIs

By specifying one of the extensions .xml or .json you're indicating which format you expect the response to be in. Examples in this document use .json. Supply .xml instead and you will be working in XML-mode.

To actually supply data correctly you need to specify the content type with your request.

Curl example:

# Updates the fmapi project from the JSON data in the local
# request.json file
curl -X PUT -d @request.json -H "Content-Type: application/json" \    
  https://freecode.com/projects/fmapi.json

Authentication

Every API request needs to be authenticated with an authentication token. You can find your personal, non-transferrable API token in your user account settings. You obviously need an active user account at Freecode. If you do not have an account yet, a new one can be created here.

Curl example:

curl -d '{ "auth_code": "XXX", "project": { "name": "New Project Name" }' \
   -X PUT -H "Content-Type: application/json" \ 
   https://freecode.com/projects/mysql.json

This sends a project update request to our servers with the PUT request, including the authentication code in the JSON request.

For GET requests, the authentication token should be supplied as a GET parameter, like so:

curl -G -d 'auth_code=XXX' https://freecode.com/projects/mysql.json

API throttling

For the time being we're imposing a limit on the number of API calls you can make per auth code per minute. This is a necessary evil to keep resource consumption controllable and ensure that we do not suffer from a denial of service attack (whether knowingly or not).

Current limit (last changed June 29, 2009):
600 API calls per auth code per 60 minutes

Response status codes

200 OK - Request was successful, the requested content is included
201 Created - Creation of a new resource was successful
401 Unauthorized - You need to provide an authentication code with this request
403 Forbidden - You don't have permission to access this URI
404 Not Found - The requested resource was not found
409 Conflict - The validation of your submitted data failed, please check the response body for error pointers
500 Server Error - The request hit a problem and was aborted, please report as a bug if it persists
503 Service Unavailable - You hit your API credit limit

Pagination

All content listings are paginated and return a sub-set of the matches only. By default, the first page of matches is returned. Successive pages may be requested with the page parameter set appropriately.

Example:

{
  "auth_code": "XXX",
  "page": 5
}

Reading and writing

Please be mindful that write permission is only granted for project admins and projects that have been explicitly set to be administered by the general public. All API requests inherit the privileges of the user account associated with the API token. And even if you are a project administrator the changes you submit will be carefully reviewed by Freecode staff before they go live.

What does this mean for the usage of the API? It means that you shouldn't rely on the API to supply you with unapproved changes you submitted a few requests back when you re-request the current state of the objects you updated. No unapproved changes will be reflected in the data the API supplies to you.

Feedback

We're still in the early days of this extended data API. If you have questions, problems, or suggestions concerning the API use, please don't hesitate to contact us via help.freecode.com.

Recent Discussions

23 Apr, 2014 08:50 AM
21 Apr, 2014 05:25 PM
19 Apr, 2014 11:44 AM
18 Apr, 2014 12:33 PM
15 Apr, 2014 12:59 PM