公共API

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.

使用 Slumber 基本的API客户端

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']

API端点

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

资源

GET /api/v1/
Retrieve a list of resources.
{
    "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:
  • list_endpoint (string) – API endpoint for resource.
  • schema (string) – API endpoint for schema of resource.

构建列表

GET /api/v1/build/
Retrieve a list of Builds.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/build/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 86684
    },
    "objects": [BUILDS]
}
Data:
  • limit (integer) – Number of Builds returned.
  • next (string) – URI for next set of Builds.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Builds.
  • total_count (integer) – Total number of Builds.
  • objects (array) – Array of `Build`_ objects.

单一构建

GET /api/v1/build/{id}/
Path arguments:id – A Build id.
Retrieve a single Build.
{
    "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:
  • date (string) – Date of Build.
  • error (string) – Error from Sphinx build process.
  • id (string) – Build id.
  • output (string) – Output from Sphinx build process.
  • project (string) – URI for Project of Build.
  • resource_uri (string) – URI for Build.
  • setup (string) – Setup output from Sphinx build process.
  • setup_error (string) – Setup error from Sphinx build process.
  • state (string) – “triggered”, “building”, or “finished”
  • success (boolean) – Was build successful?
  • type (string) – Build type (“html”, “pdf”, “man”, or “epub”)
  • version (string) – URI for Version of Build.

文件列表

GET /api/v1/file/
Retrieve a list of Files.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/file/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 32084
    },
    "objects": [FILES]
}
Data:
  • limit (integer) – Number of Files returned.
  • next (string) – URI for next set of Files.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Files.
  • total_count (integer) – Total number of Files.
  • objects (array) – Array of `File`_ objects.

单一文件

GET /api/v1/file/{id}/
Path arguments:id – A File id.
Retrieve a single File.
{
    "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:
  • absolute_url (string) – URI for actual file (not the File object from the API.)
  • id (string) – File id.
  • name (string) – Name of File.
  • path (string) – Name of Path.
  • project (object) – A `Project`_ object for the file’s project.
  • resource_uri (string) – URI for File object.

项目列表

GET /api/v1/project/
Retrieve a list of Projects.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/project/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 2067
    },
    "objects": [PROJECTS]
}
Data:
  • limit (integer) – Number of Projects returned.
  • next (string) – URI for next set of Projects.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Projects.
  • total_count (integer) – Total number of Projects.
  • objects (array) – Array of `Project`_ objects.

单一项目

GET /api/v1/project/{id}
Path arguments:id – A Project id.
Retrieve a single Project.
{
    "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:
  • absolute_url (string) – URI for project (not the Project object from the API.)
  • analytics_code (string) – Analytics tracking code.
  • copyright (string) – Copyright
  • crate_url (string) – Crate.io URI.
  • default_branch (string) – Default branch.
  • default_version (string) – Default version.
  • description (string) – Description of project.
  • django_packages_url (string) – Djangopackages.com URI.
  • documentation_type (string) – Either “sphinx” or “sphinx_html”.
  • id (string) – Project id.
  • modified_date (string) – Last modified date.
  • name (string) – Project name.
  • project_url (string) – Project homepage.
  • pub_date (string) – Last published date.
  • repo (string) – URI for VCS repository.
  • repo_type (string) – Type of VCS repository.
  • requirements_file (string) – Pip requirements file for packages needed for building docs.
  • resource_uri (string) – URI for Project.
  • slug (string) – Slug.
  • subdomain (string) – Subdomain.
  • suffix (string) – File suffix of docfiles. (Usually ”.rst”.)
  • theme (string) – Sphinx theme.
  • use_virtualenv (boolean) – Build project in a virtualenv? (True or False)
  • users (array) – Array of readthedocs.org user URIs for administrators of Project.
  • version (string) – DEPRECATED.

用户列表

GET /api/v1/user/
Retrieve List of Users
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/user/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 3200
    },
    "objects": [USERS]
}
Data:
  • limit (integer) – Number of Users returned.
  • next (string) – URI for next set of Users.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Users.
  • total_count (integer) – Total number of Users.
  • USERS (array) – Array of `User`_ objects.

单一用户

GET /api/v1/user/{id}/
Path arguments:id – A User id.
Retrieve a single User
{
    "first_name": "",
    "id": "1",
    "last_login": "2010-10-28T13:38:13.022687",
    "last_name": "",
    "resource_uri": "/api/v1/user/1/",
    "username": "testuser"
}
Data:
  • first_name (string) – First name.
  • id (string) – User id.
  • last_login (string) – Timestamp of last login.
  • last_name (string) – Last name.
  • resource_uri (string) – URI for this user.
  • username (string) – User name.

版本列表

GET /api/v1/version/
Retrieve a list of Versions.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/version/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 16437
    },
    "objects": [VERSIONS]
}
Data:
  • limit (integer) – Number of Versions returned.
  • next (string) – URI for next set of Versions.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Versions.
  • total_count (integer) – Total number of Versions.
  • objects (array) – Array of `Version`_ objects.

单一版本

GET /api/v1/version/{id}
Path arguments:id – A Version id.
Retrieve a single Version.
{
    "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:
  • active (boolean) – Are we continuing to build docs for this version?
  • built (boolean) – Have docs been built for this version?
  • id (string) – Version id.
  • identifier (string) – Identifier of Version.
  • project (object) – A `Project`_ object for the version’s project.
  • resource_uri (string) – URI for Version object.
  • slug (string) – String that uniquely identifies a project
  • uploaded (boolean) – Were docs uploaded? (As opposed to being build by Read the Docs.)
  • verbose_name (string) – Usually the same as Slug.

过滤的例子

最高版本

http://readthedocs.org/api/v1/version/pip/highest/?format=json
GET /api/v1/version/{id}/highest/
Path arguments:id – A Version id.
Retrieve highest version.
{
    "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
GET /api/v1/version/{id}/highest/{version}
Path arguments:
  • id – A Version id.
  • version – A Version number or string.
Retrieve highest version.
{
    "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
GET /api/v1/file/search/?q={search_term}
Path arguments:search_term – Perform search with this term.
Retrieve a list of File objects that contain the search 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
GET /api/v1/file/anchor/?q={search_term}
Path arguments:search_term – Perform search of files containing anchor text with this term.
Retrieve a list of absolute URIs for files that contain the search 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",
        ...
    ]
}
Read the Docs v: latest
Versions
latest
Downloads
PDF
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.