diff --git a/docs/api/builds.rst b/docs/api/builds.rst
deleted file mode 100644
index c8476c398ea..00000000000
--- a/docs/api/builds.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-:mod:`readthedocs.builds`
-=========================
-
-:mod:`readthedocs.builds.admin`
--------------------------------
-.. automodule:: readthedocs.builds.admin
- :members:
-
-:mod:`readthedocs.builds.models`
---------------------------------
-.. automodule:: readthedocs.builds.models
- :members:
-
-:mod:`readthedocs.builds.urls`
-------------------------------
-.. automodule:: readthedocs.builds.urls
- :members:
-
-:mod:`readthedocs.builds.views`
--------------------------------
-.. automodule:: readthedocs.builds.views
- :members:
-
diff --git a/docs/api/core.rst b/docs/api/core.rst
deleted file mode 100644
index b0b99966212..00000000000
--- a/docs/api/core.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-:mod:`readthedocs.core`
-=======================
-
-:mod:`readthedocs.core.admin`
------------------------------
-.. automodule:: readthedocs.core.admin
- :members:
-
-:mod:`readthedocs.core.forms`
------------------------------
-.. automodule:: readthedocs.core.forms
- :members:
-
-:mod:`readthedocs.core.middleware`
-----------------------------------
-.. automodule:: readthedocs.core.middleware
- :members:
-
-:mod:`readthedocs.core.models`
-------------------------------
-.. automodule:: readthedocs.core.models
- :members:
-
-:mod:`readthedocs.core.views`
------------------------------
-.. automodule:: readthedocs.core.views
- :members:
-
-
-:mod:`readthedocs.core.management.commands`
--------------------------------------------
-This is where custom ``manage.py`` commands are defined.
-
-.. automodule:: readthedocs.core.management.commands.archive
- :members:
-
-.. automodule:: readthedocs.core.management.commands.clean_builds
- :members:
-
-.. automodule:: readthedocs.core.management.commands.import_github_language
- :members:
-
-.. automodule:: readthedocs.core.management.commands.import_github
- :members:
-
-.. automodule:: readthedocs.core.management.commands.pull
- :members:
-
-.. automodule:: readthedocs.core.management.commands.reindex_elasticsearch
- :members:
-
-.. automodule:: readthedocs.core.management.commands.set_metadata
- :members:
-
-.. automodule:: readthedocs.core.management.commands.symlink
- :members:
-
-.. automodule:: readthedocs.core.management.commands.update_api
- :members:
-
-.. automodule:: readthedocs.core.management.commands.update_repos
- :members:
-
-.. automodule:: readthedocs.core.management.commands.update_versions
- :members:
diff --git a/docs/api/doc_builder.rst b/docs/api/doc_builder.rst
deleted file mode 100644
index 10580d9c91d..00000000000
--- a/docs/api/doc_builder.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-:mod:`readthedocs.doc_builder`
-==============================
-
-:mod:`readthedocs.doc_builder.base`
------------------------------------
-.. automodule:: readthedocs.doc_builder.base
- :members:
-
-:mod:`readthedocs.doc_builder.environments`
--------------------------------------------
-.. automodule:: readthedocs.doc_builder.environments
- :members:
-
-:mod:`readthedocs.doc_builder.backends`
----------------------------------------
-
-
-:mod:`readthedocs.doc_builder.backends.sphinx`
-----------------------------------------------
-.. automodule:: readthedocs.doc_builder.backends.sphinx
- :members:
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 1d78be1b363..6e263bdefeb 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -1,13 +1,26 @@
-API
-===
+Public API
+==========
+
+This section of the documentation details the public API
+usable to get details of projects, builds, versions and other details
+from Read the Docs.
+
+.. warning::
+
+ Originally, the Read the Docs API allowed connections over insecure HTTP.
+ Starting in January 2019, requests over HTTP
+ will be automatically redirected to HTTPS
+ and non-GET/HEAD requests over insecure HTTP will fail.
+
+.. tip::
+
+ It is a good idea to put your email address, application name,
+ or Read the Docs username into the user agent header of your requests.
+ That way the Read the Docs' team can contact you in the event of issues.
-This is the Read The Docs API documentation, autogenerated from the source
-code.
.. toctree::
+ :maxdepth: 3
- builds
- doc_builder
- core
- projects
- vcs_support
+ v2
+ v1
diff --git a/docs/api/projects.rst b/docs/api/projects.rst
deleted file mode 100644
index d17907f916d..00000000000
--- a/docs/api/projects.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-:mod:`readthedocs.projects`
-===========================
-
-:mod:`readthedocs.projects.admin`
----------------------------------
-.. automodule:: readthedocs.projects.admin
- :members:
-
-:mod:`readthedocs.projects.constants`
--------------------------------------
-.. automodule:: readthedocs.projects.constants
- :members:
-
-:mod:`readthedocs.projects.forms`
----------------------------------
-.. automodule:: readthedocs.projects.forms
- :members:
-
-:mod:`readthedocs.projects.models`
-----------------------------------
-.. automodule:: readthedocs.projects.models
- :members:
-
-:mod:`readthedocs.projects.tasks`
----------------------------------
-.. automodule:: readthedocs.projects.tasks
- :members:
-
-:mod:`readthedocs.projects.utils`
----------------------------------
-.. automodule:: readthedocs.projects.utils
- :members:
-
-:mod:`readthedocs.projects.views`
----------------------------------
-
-:mod:`readthedocs.projects.views.public`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. automodule:: readthedocs.projects.views.public
- :members:
-
-:mod:`readthedocs.projects.views.private`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. automodule:: readthedocs.projects.views.private
- :members:
-
diff --git a/docs/api.rst b/docs/api/v1.rst
similarity index 96%
rename from docs/api.rst
rename to docs/api/v1.rst
index d1204960a73..a8c9e047130 100644
--- a/docs/api.rst
+++ b/docs/api/v1.rst
@@ -1,11 +1,14 @@
-Read the Docs Public API
-=========================
+API v1 (deprecated)
+===================
We have a limited public API that is available for you to get data out of the site.
This document covers only part of the API provided. We have plans to create a read/write API, so that you can easily automate interactions with your project.
-.. warning:: This API is out of date and not currently maintained.
- We have a v2 API that is currently supported at http://readthedocs.org/api/v2/.
+.. warning::
+
+ This API is **deprecated** but will be maintained through at least January 2019.
+ Please connect with :doc:`/api/v2`.
+
A basic API client using slumber
--------------------------------
@@ -17,7 +20,7 @@ You can use `Slumber `_ to build basic API wrapp
import json
show_objs = True
- api = slumber.API(base_url='http://readthedocs.org/api/v1/')
+ api = slumber.API(base_url='https://readthedocs.org/api/v1/')
val = api.project.get(slug='pip')
@@ -52,7 +55,7 @@ Feel free to use cURL and python to look at formatted json examples. You can als
::
- curl http://readthedocs.org/api/v1/project/pip/?format=json | python -m json.tool
+ curl https://readthedocs.org/api/v1/project/pip/?format=json | python -m json.tool
Doc Search
----------
@@ -69,7 +72,7 @@ Doc Search
In the future we might change the format of this endpoint to make it more abstact.
- An example URL: http://readthedocs.org/api/v2/docsearch/?project=docs&version=latest&q=subdomains
+ An example URL: https://readthedocs.org/api/v2/docsearch/?project=docs&version=latest&q=subdomains
Results:
@@ -486,7 +489,7 @@ File Search
~~~~~~~~~~~
::
- http://readthedocs.org/api/v1/file/search/?format=json&q=virtualenvwrapper
+ https://readthedocs.org/api/v1/file/search/?format=json&q=virtualenvwrapper
.. http:get:: /api/v1/file/search/?q={search_term}
@@ -543,7 +546,7 @@ Anchor Search
~~~~~~~~~~~~~
::
- http://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv
+ https://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv
.. http:get:: /api/v1/file/anchor/?q={search_term}
diff --git a/docs/api/v2.rst b/docs/api/v2.rst
new file mode 100644
index 00000000000..05342f21e38
--- /dev/null
+++ b/docs/api/v2.rst
@@ -0,0 +1,310 @@
+API v2
+======
+
+The Read the Docs API uses :abbr:`REST (Representational State Transfer)`.
+JSON is returned by all API responses including errors
+and HTTP response status codes are to designate success and failure.
+
+.. note::
+
+ A newer API v3 is in early development stages.
+ Some improvements coming in v3 are:
+
+ * Search API
+ * Write access
+ * Simpler URLs which use slugs instead of numeric IDs
+ * Improved error reporting
+
+ If there are features you would like in v3, please get in touch
+ in the `issue tracker `_.
+
+
+Authentication and authorization
+--------------------------------
+
+Requests to the Read the Docs public API are for public information only
+and do not require any authentication.
+
+
+Resources
+---------
+
+Projects
+~~~~~~~~
+
+Projects are the main building block of Read the Docs.
+Projects are built when there are changes to the code
+and the resulting documentation is hosted and served by Read the Docs.
+
+As an example, this documentation is part of the `Docs project`_
+which has documentation at https://docs.readthedocs.io.
+
+You can always view your Read the Docs projects in your `project dashboard`_.
+
+.. _Docs project: https://readthedocs.org/projects/docs/
+.. _project dashboard: https://readthedocs.org/dashboard/
+
+Project list
+++++++++++++
+
+.. http:get:: /api/v2/project/
+
+ Retrieve a list of all Read the Docs projects.
+
+ .. sourcecode:: js
+
+ {
+ "count": 10000,
+ "next": "http://readthedocs.org/api/v2/project/?page=2",
+ "previous": null,
+ "results": [PROJECTS]
+ }
+
+ :>json string next: URI for next set of Projects.
+ :>json string previous: URI for previous set of Projects.
+ :>json integer count: Total number of Projects.
+ :>json array objects: Array of ``Project`` objects.
+
+Project details
++++++++++++++++
+
+.. http:get:: /api/v2/project/(int:id)/
+
+ Retrieve details of a single project.
+
+ .. sourcecode:: js
+
+ {
+ "id": 6,
+ "name": "Pip",
+ "slug": "pip",
+ "programming_language": "py",
+ "default_version": "stable",
+ "default_branch": "master",
+ "repo_type": "git",
+ "repo": "https://github.com/pypa/pip",
+ "description": "Pip Installs Packages.",
+ "language": "en",
+ "documentation_type": "sphinx_htmldir",
+ "canonical_url": "http://pip.pypa.io/en/stable/",
+ "users": [USERS]
+ }
+
+
+ :>json integer id: The ID of the project
+ :>json string name: The name of the project.
+ :>json string slug: The project slug (used in the URL).
+ :>json string programming_language: The programming language of the project (eg. "py", "js")
+ :>json string default_version: The default version of the project (eg. "latest", "stable", "v3")
+ :>json string default_branch: The default version control branch
+ :>json string repo_type: Version control repository of the project
+ :>json string repo: The repository URL for the project
+ :>json string description: An RST description of the project
+ :>json string language: The language code of this project
+ :>json string documentation_type: An RST description of the project
+ :>json string canonical_url: The canonical URL of the default docs
+ :>json array users: Array of ``User`` IDs who are maintainers of the project.
+
+ :statuscode 200: no error
+ :statuscode 404: There is no ``Project`` with this ID
+
+Project versions
+++++++++++++++++
+
+.. http:get:: /api/v2/project/(int:id)/active_versions/
+
+ Retrieve a list of active versions (eg. "latest", "stable", "v1.x") for a single project.
+
+ .. sourcecode:: js
+
+ {
+ "versions": [
+ {
+ "id": 1437428,
+ "slug": "stable",
+ "verbose_name": "stable",
+ "built": true,
+ "active": true,
+ "type": "tag",
+ "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914",
+ "downloads": {
+ "pdf": "//readthedocs.org/projects/pip/downloads/pdf/stable/",
+ "htmlzip": "//readthedocs.org/projects/pip/downloads/htmlzip/stable/",
+ "epub": "//readthedocs.org/projects/pip/downloads/epub/stable/"
+ },
+ "project": {PROJECT},
+ },
+ ...
+ ]
+ }
+
+
+ :>json integer id: The ID of the version
+ :>json string verbose_name: The name of the version.
+ :>json string slug: The version slug.
+ :>json string built: Whether this version has been built
+ :>json string active: Whether this version is still active
+ :>json string type: The type of this version (typically "tag" or "branch")
+ :>json string identifier: A version control identifier for this version (eg. the commit hash of the tag)
+ :>json array downloads: URLs to downloads of this version's documentation
+ :>json object project: Details of the ``Project`` for this version.
+
+
+Versions
+~~~~~~~~
+
+Versions are different versions of the same project documentation
+
+The versions for a given project can be viewed in a project's version screen.
+For example, here is the `Pip project's version screen`_.
+
+.. _Pip project's version screen: https://readthedocs.org/projects/pip/versions/
+
+Version list
+++++++++++++
+
+.. http:get:: /api/v2/version/
+
+ Retrieve a list of all Versions for all projects (10 at a time).
+
+ .. sourcecode:: js
+
+ {
+ "count": 1000,
+ "previous": null,
+ "results": [VERSIONS],
+ "next": "http://readthedocs.org/api/v2/version/?limit=10&offset=10"
+ }
+
+
+ :>json string next: URI for next set of Versions.
+ :>json string previous: URI for previous set of Versions.
+ :>json integer count: Total number of Versions.
+ :>json array objects: Array of ``Version`` objects.
+
+Version detail
+++++++++++++++
+
+.. http:get:: /api/v2/version/(int:id)/
+
+ Retrieve details of a single version.
+
+ .. sourcecode:: js
+
+ {
+ "id": 1437428,
+ "slug": "stable",
+ "verbose_name": "stable",
+ "built": true,
+ "active": true,
+ "type": "tag",
+ "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914",
+ "downloads": {
+ "pdf": "//readthedocs.org/projects/pip/downloads/pdf/stable/",
+ "htmlzip": "//readthedocs.org/projects/pip/downloads/htmlzip/stable/",
+ "epub": "//readthedocs.org/projects/pip/downloads/epub/stable/"
+ },
+ "project": {PROJECT},
+ }
+
+ :>json integer id: The ID of the version
+ :>json string verbose_name: The name of the version.
+ :>json string slug: The version slug.
+ :>json string built: Whether this version has been built
+ :>json string active: Whether this version is still active
+ :>json string type: The type of this version (typically "tag" or "branch")
+ :>json string identifier: A version control identifier for this version (eg. the commit hash of the tag)
+ :>json array downloads: URLs to downloads of this version's documentation
+ :>json object project: Details of the ``Project`` for this version.
+
+ :statuscode 200: no error
+ :statuscode 404: There is no ``Version`` with this ID
+
+
+Builds
+~~~~~~
+
+Builds are created by Read the Docs whenever a ``Project`` has its documentation built.
+Frequently this happens automatically via a web hook but can be triggered manually.
+
+Builds can be viewed in the build screen for a project.
+For example, here is `Pip's build screen`_.
+
+.. _Pip's build screen: https://readthedocs.org/projects/pip/builds/
+
+.. The build list API fails with no parameters.
+ As a result, I'm going to leave it undocumented.
+
+Build detail
+++++++++++++++
+
+.. http:get:: /api/v2/build/(int:id)/
+
+ Retrieve details of a single build.
+
+ .. sourcecode:: js
+
+ {
+ "id": 7367364,
+ "date": "2018-06-19T15:15:59.135894",
+ "length": 59,
+ "type": "html",
+ "state": "finished",
+ "success": true,
+ "error": "",
+ "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30",
+ "docs_url": "http://pip.pypa.io/en/latest/",
+ "project": 13,
+ "project_slug": "pip",
+ "version": 3681,
+ "version_slug": "latest",
+ "commands": [
+ {
+ "description": "",
+ "start_time": "2018-06-19T20:16:00.951959",
+ "exit_code": 0,
+ "build": 7367364,
+ "command": "git remote set-url origin git://github.com/pypa/pip.git",
+ "run_time": 0,
+ "output": "",
+ "id": 42852216,
+ "end_time": "2018-06-19T20:16:00.969170"
+ },
+ ...
+ ],
+ ...
+ }
+
+
+ :>json integer id: The ID of the build
+ :>json string date: The ISO-8601 datetime of the build.
+ :>json integer length: The length of the build in seconds.
+ :>json string type: The type of the build (one of "html", "pdf", "epub")
+ :>json string state: The state of the build (one of "triggered", "building", "installing", "cloning", or "finished")
+ :>json boolean success: Whether the build was successful
+ :>json string error: An error message if the build was unsuccessful
+ :>json string commit: A version control identifier for this build (eg. the commit hash)
+ :>json string docs_url: The canonical URL of the build docs
+ :>json integer project: The ID of the project being built
+ :>json string project_slug: The slug for the project being built
+ :>json integer version: The ID of the version of the project being built
+ :>json string version_slug: The slug for the version of the project being built
+ :>json array commands: Array of commands for the build with details including output.
+
+ :statuscode 200: no error
+ :statuscode 404: There is no ``Build`` with this ID
+
+ Some fields primarily used for UI elements in Read the Docs are omitted.
+
+Undocumented resources and endpoints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are some undocumented endpoints in the API.
+These should not be used and could change at any time.
+These include:
+
+* The search API (``/api/v2/search/``)
+* Endpoints for returning footer and version data to be injected into docs.
+ (``/api/v2/footer_html``)
+* Endpoints used for advertising (``/api/v2/sustainability/``)
+* Any other endpoints not detailed above.
diff --git a/docs/api/vcs_support.rst b/docs/api/vcs_support.rst
deleted file mode 100644
index d801503a0e9..00000000000
--- a/docs/api/vcs_support.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-:mod:`readthedocs.vcs_support`
-==============================
-
-:mod:`readthedocs.vcs_support.base`
------------------------------------
-
-.. automodule:: readthedocs.vcs_support.base
- :members:
-
diff --git a/docs/builds.rst b/docs/builds.rst
index 3adc1e2774e..3cdf2123651 100644
--- a/docs/builds.rst
+++ b/docs/builds.rst
@@ -108,7 +108,7 @@ Writing your own builder
The documentation build system in RTD is made pluggable, so that you can build out your own backend. If you have a documentation format that isn't currently supported, you can add support by contributing a backend.
-The :doc:`api/doc_builder` API explains the higher level parts of the API that you need to implement. A basic run goes something like this::
+The builders in :doc:`/developer-interface/doc_builder` detail the higher level parts of the API that you need to implement. A basic run goes something like this::
backend = get_backend(project.documentation_type)
if force:
diff --git a/docs/index.rst b/docs/index.rst
index e421ef3da85..1aac582e0b2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -44,7 +44,7 @@ Information about development is also available:
faq
yaml-config
guides/index
- api
+ api/index
embed
.. _about-docs:
@@ -105,7 +105,6 @@ Information about development is also available:
i18n
issue-labels
security
- api/index
.. _business-docs: