We have a limited public API that is available for you to get data out of the site. This page will only show a few of the basic parts, please file a ticket or ping us on IRC (#readthedocs on Freenode (chat.freenode.net)) if you have feature requests.
This document covers the read-only API provided. We have plans to create a read/write API, so that you can easily automate interactions with your project.
The API is written in Tastypie, which provides a nice ability to browse the API from your browser. If you go to http://readthedocs.org/api/v1/?format=json and just poke around, you should be able to figure out what is going on.
You can use Slumber to build basic API wrappers in python. Here is a simple example of using slumber to interact with the RTD API:
import slumber
import json
show_objs = True
api = slumber.API(base_url='http://readthedocs.org/api/v1/')
val = api.project.get(slug='pip')
#val = api.project('pip').get()
#val = api.build(49252).get()
#val = api.build.get(project__slug='read-the-docs')
#val = api.user.get(username='eric')
#val = api.version('pip').get()
#val = api.version('pip').get(slug='1.0.1')
#val = api.version('pip').highest.get()
#val = api.version('pip').highest('0.8').get()
if show_objs:
for obj in val['objects']:
print json.dumps(obj, indent=4)
else:
print json.dumps(val, indent=4)
import slumber
USERNAME = 'eric'
PASSWORD = 'test'
user_to_add = 'coleifer'
project_slug = 'read-the-docs'
api = slumber.API(base_url='http://readthedocs.org/api/v1/', authentication={'name': USERNAME, 'password': PASSWORD})
project = api.project.get(slug=project_slug)
user = api.user.get(username=user_to_add)
project_objects = project['objects'][0]
user_objects = user['objects'][0]
data = {'users': project_objects['users'][:]}
data['users'].append(user_objects['resource_uri'])
print "Adding %s to %s" % (user_objects['username'], project_objects['slug'])
api.project(project_objects['id']).put(data)
project2 = api.project.get(slug=project_slug)
project2_objects = project2['objects'][0]
print "Before users: %s" % project_objects['users']
print "After users: %s" % project2_objects['users']
Feel free to use cURL and python to look at formatted json examples. You can also look at them in your browser, if it handles returned json.
curl http://readthedocs.org/api/v1/project/pip/?format=json | python -m json.tool
{
"build": {
"list_endpoint": "/api/v1/build/",
"schema": "/api/v1/build/schema/"
},
"file": {
"list_endpoint": "/api/v1/file/",
"schema": "/api/v1/file/schema/"
},
"project": {
"list_endpoint": "/api/v1/project/",
"schema": "/api/v1/project/schema/"
},
"user": {
"list_endpoint": "/api/v1/user/",
"schema": "/api/v1/user/schema/"
},
"version": {
"list_endpoint": "/api/v1/version/",
"schema": "/api/v1/version/schema/"
}
}
Data: |
|
---|
{
"meta": {
"limit": 20,
"next": "/api/v1/build/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 86684
},
"objects": [BUILDS]
}
Data: |
|
---|
Path arguments: | id – A Build id. |
---|
{
"date": "2012-03-12T19:58:29.307403",
"error": "SPHINX ERROR",
"id": "91207",
"output": "SPHINX OUTPUT",
"project": "/api/v1/project/2599/",
"resource_uri": "/api/v1/build/91207/",
"setup": "HEAD is now at cd00d00 Merge pull request #181 from Nagyman/solr_setup\n",
"setup_error": "",
"state": "finished",
"success": true,
"type": "html",
"version": "/api/v1/version/37405/"
}
Data: |
|
---|
{
"meta": {
"limit": 20,
"next": "/api/v1/file/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 32084
},
"objects": [FILES]
}
Data: |
|
---|
Path arguments: | id – A File id. |
---|
{
"absolute_url": "/docs/keystone/en/latest/search.html",
"id": "332692",
"name": "search.html",
"path": "search.html",
"project": {PROJECT},
"resource_uri": "/api/v1/file/332692/"
}
Data: |
|
---|
{
"meta": {
"limit": 20,
"next": "/api/v1/project/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 2067
},
"objects": [PROJECTS]
}
Data: |
|
---|
Path arguments: | id – A Project id. |
---|
{
"absolute_url": "/projects/docs/",
"analytics_code": "",
"copyright": "",
"crate_url": "",
"default_branch": "",
"default_version": "latest",
"description": "Make docs.readthedocs.org work :D",
"django_packages_url": "",
"documentation_type": "sphinx",
"id": "2599",
"modified_date": "2012-03-12T19:59:09.130773",
"name": "docs",
"project_url": "",
"pub_date": "2012-02-19T18:10:56.582780",
"repo": "git://github.com/rtfd/readthedocs.org",
"repo_type": "git",
"requirements_file": "",
"resource_uri": "/api/v1/project/2599/",
"slug": "docs",
"subdomain": "http://docs.readthedocs.org/",
"suffix": ".rst",
"theme": "default",
"use_virtualenv": false,
"users": [
"/api/v1/user/1/"
],
"version": ""
}
Data: |
|
---|
{
"meta": {
"limit": 20,
"next": "/api/v1/user/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 3200
},
"objects": [USERS]
}
Data: |
|
---|
Path arguments: | id – A User id. |
---|
{
"first_name": "",
"id": "1",
"last_login": "2010-10-28T13:38:13.022687",
"last_name": "",
"resource_uri": "/api/v1/user/1/",
"username": "testuser"
}
Data: |
|
---|
{
"meta": {
"limit": 20,
"next": "/api/v1/version/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 16437
},
"objects": [VERSIONS]
}
Data: |
|
---|
Path arguments: | id – A Version id. |
---|
{
"active": false,
"built": false,
"id": "12095",
"identifier": "remotes/origin/zip_importing",
"project": {PROJECT},
"resource_uri": "/api/v1/version/12095/",
"slug": "zip_importing",
"uploaded": false,
"verbose_name": "zip_importing"
}
Data: |
|
---|
http://readthedocs.org/api/v1/version/pip/highest/?format=json
Path arguments: | id – A Version id. |
---|
{
"is_highest": true,
"project": "Version 1.0.1 of pip (5476)",
"slug": [
"1.0.1"
],
"url": "/docs/pip/en/1.0.1/",
"version": "1.0.1"
}
This will allow you to compare whether a certain version is the highest version of a specific project. The below query should return a 'is_highest': false in the returned dictionary.
http://readthedocs.org/api/v1/version/pip/highest/0.8/?format=json
Path arguments: |
|
---|
{
"is_highest": false,
"project": "Version 1.0.1 of pip (5476)",
"slug": [
"1.0.1"
],
"url": "/docs/pip/en/1.0.1/",
"version": "1.0.1"
}
http://readthedocs.org/api/v1/file/search/?format=json&q=virtualenvwrapper
Path arguments: | search_term – Perform search with this term. |
---|
{
"objects": [
{
"absolute_url": "/docs/python-guide/en/latest/scenarios/virtualenvs/index.html",
"id": "375539",
"name": "index.html",
"path": "scenarios/virtualenvs/index.html",
"project": {
"absolute_url": "/projects/python-guide/",
"analytics_code": null,
"copyright": "Unknown",
"crate_url": "",
"default_branch": "",
"default_version": "latest",
"description": "[WIP] Python best practices...",
"django_packages_url": "",
"documentation_type": "sphinx_htmldir",
"id": "530",
"modified_date": "2012-03-13T01:05:30.191496",
"name": "python-guide",
"project_url": "",
"pub_date": "2011-03-20T19:40:03.599987",
"repo": "git://github.com/kennethreitz/python-guide.git",
"repo_type": "git",
"requirements_file": "",
"resource_uri": "/api/v1/project/530/",
"slug": "python-guide",
"subdomain": "http://python-guide.readthedocs.org/",
"suffix": ".rst",
"theme": "kr",
"use_virtualenv": false,
"users": [
"/api/v1/user/130/"
],
"version": ""
},
"resource_uri": "/api/v1/file/375539/",
"text": "...<span class=\"highlighted\">virtualenvwrapper</span>\n..."
},
...
]
}
http://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv
Path arguments: | search_term – Perform search of files containing anchor text with this term. |
---|
{
"objects": [
"http//django-fab-deploy.readthedocs.org/en/latest/...",
"http//dimagi-deployment-tools.readthedocs.org/en/...",
"http//openblock.readthedocs.org/en/latest/install/base_install.html#virtualenv",
...
]
}