EbookFoundation
/
readthedocs.org
mirror of https://github.com/EbookFoundation/readthedocs.org.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

First pass at documenting API.

rtd2
Tom Offermann 2012-03-12 20:52:18 -07:00
parent 42fff2d232
commit 31513e2150
3 changed files with 370 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

368
docs/api.rst
View File

@ -136,3 +136,371 @@ URL
```
http://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv
Public API
==========
All examples are shown with JSON responses, but you may also get XML by specifying the format.
Base
----
.. http:method:: GET /api/v1/
.. http:response:: Retrieve a list of resources.
.. sourcecode:: js
{
"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/"
}
}
Builds
~~~~~~
.. http:method:: GET /api/v1/build/
.. http:response:: Retrieve a list of Builds.
.. sourcecode:: js
{
"meta": {
"limit": 20,
"next": "/api/v1/build/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 86684
},
"objects": [BUILDS]
}
:data integer limit: Number of Builds returned.
:data string next: URI for next set of Builds.
:data integer offset: Current offset used for pagination.
:data string previous: URI for previous set of Builds.
:data integer total_count: Total number of Builds.
:data string objects: List of `Build`_ objects.
Build
~~~~~
.. http:method:: GET /api/v1/build/{id}/
:arg id: A Build id.
.. http:response:: Retrieve a single Build.
.. sourcecode:: js
{
"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 string date: Date of Build.
:data string error: Error from Sphinx build process.
:data string id: Build id.
:data string output: Output from Sphinx build process.
:data string project: URI for Project of Build.
:data string resource_uri: URI for Build.
:data string setup: Setup output from Sphinx build process.
:data string setup_error: Setup error from Sphinx build process.
:data string state:
:data string success: Was build successful? (True or False)
:data string type: Build type (html, pdf, man, or epub)
:data string version: URI for Version of Build.
Files
~~~~~
.. http:method:: GET /api/v1/file/
.. http:response:: Retrieve a list of Files.
.. sourcecode:: js
{
"meta": {
"limit": 20,
"next": "/api/v1/file/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 32084
},
"objects": [FILES]
}
:data integer limit: Number of Files returned.
:data string next: URI for next set of Files.
:data integer offset: Current offset used for pagination.
:data string previous: URI for previous set of Files.
:data integer total_count: Total number of Files.
:data string objects: List of `File`_ objects.
File
~~~~
.. http:method:: GET /api/v1/file/{id}/
:arg id: A File id.
.. http:response:: Retrieve a single File.
.. sourcecode:: js
{
"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 string absolute_url: URI for actual file (not the File object from the API.)
:data string id: File id.
:data string name: Name of File.
:data string path: Name of Path.
:data string project: A `Project`_ object for the file's project.
:data string resource_uri: URI for File object.
Projects
~~~~~~~~
.. http:method:: GET /api/v1/project/
.. http:response:: Retrieve a list of Projects.
.. sourcecode:: js
{
"meta": {
"limit": 20,
"next": "/api/v1/project/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 2067
},
"objects": [PROJECTS]
}
:data integer limit: Number of Projects returned.
:data string next: URI for next set of Projects.
:data integer offset: Current offset used for pagination.
:data string previous: URI for previous set of Projects.
:data integer total_count: Total number of Projects.
:data string objects: List of `Project`_ objects.
Project
~~~~~~~
.. http:method:: GET /api/v1/project/{id}
:arg id: A Project id.
.. http:response:: Retrieve a single Project.
.. sourcecode:: js
{
"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 string absolute_url: URI for project (not the Project object from the API.)
:data string analytics_code: Analytics tracking code.
:data string copyright: Copyright
:data string crate_url: Crate.io URI.
:data string default_branch: Default branch.
:data string default_version: Default version.
:data string description: Description of project.
:data string django_packages_url: Djangopackages.com URI.
:data string documentation_type: FIXME:
:data string id: Project id.
:data string modified_date: Last modified date.
:data string name: Project name.
:data string project_url: FIXME:
:data string pub_date: Last published date.
:data string repo: URI for VCS repository.
:data string repo_type: Type of VCS repository.
:data string requirements_file: FIXME:
:data string resource_uri: URI for Project.
:data string slug: Slug.
:data string subdomain: Subdomain.
:data string suffix: FIXME:
:data string theme: Sphinx theme.
:data string use_virtualenv: Build project in a virtualenv? (True or False)
:data string users: List of readthedocs.org users that are administrators of Project.
:data string version: FIXME:
Users
~~~~~
.. http:method:: GET /api/v1/user/
.. http:response:: Retrieve List of Users
.. sourcecode:: js
{
"meta": {
"limit": 20,
"next": "/api/v1/user/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 3200
},
"objects": [USERS]
}
:data integer limit: Number of Users returned.
:data string next: URI for next set of Users.
:data integer offset: Current offset used for pagination.
:data string previous: URI for previous set of Users.
:data integer total_count: Total number of Users.
:data string USERS: List of `User`_ objects.
User
~~~~
.. http:method:: GET /api/v1/user/{id}/
:arg id: A User id.
.. http:response:: Retrieve a single User
.. sourcecode:: js
{
"first_name": "",
"id": "1",
"last_login": "2010-10-28T13:38:13.022687",
"last_name": "",
"resource_uri": "/api/v1/user/1/",
"username": "testuser"
}
:data integer first_name: First name.
:data string id: User id.
:data string last_login: Timestamp of last login.
:data string last_name: Last name.
:data string resource_uri: URI for this user.
:data string username: User name.
Versions
~~~~~~~~
.. http:method:: GET /api/v1/version/
.. http:response:: Retrieve a list of Versions.
.. sourcecode:: js
{
"meta": {
"limit": 20,
"next": "/api/v1/version/?limit=20&offset=20",
"offset": 0,
"previous": null,
"total_count": 16437
},
"objects": [VERSIONS]
}
:data integer limit: Number of Versions returned.
:data string next: URI for next set of Versions.
:data integer offset: Current offset used for pagination.
:data string previous: URI for previous set of Versions.
:data integer total_count: Total number of Versions.
:data string objects: A list of `Version`_ objects.
Version
~~~~~~~
.. http:method:: GET /api/v1/version/{id}
:arg id: A Version id.
.. http:response:: Retrieve a single Version.
.. sourcecode:: js
{
"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 string active: FIXME:
:data string built: Were docs built for this Version? (True or False)
:data string id: Version id.
:data string identifier: Identifier of Version.
:data string project: A `Project`_ object for the version's project.
:data string resource_uri: URI for Version object.
:data string slug: Slug.
:data string uploaded: Was Version uploaded? (True or False) FIXME:
:data string verbose_name: FIXME:

2
docs/conf.py
View File

@ -6,7 +6,7 @@ import settings.sqlite
from django.core.management import setup_environ
setup_environ(settings.sqlite)
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx_http_domain']
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'

2
pip_requirements.txt
View File

@ -26,4 +26,4 @@ slumber
-e git+http://github.com/nathanborror/django-registration.git#egg=django-registration
-e git+https://github.com/toastdriven/django-tastypie.git#egg=tastypie
-e git+https://github.com/toastdriven/django-haystack#egg=django-haystack
-e git+https://github.com/deceze/Sphinx-HTTP-domain.git#egg=sphinx-http-domain