Merge pull request #4274 from rtfd/davidfischer/document-api-v2

Add documentation for APIv2
readthedocs · Jun 21, 2018 · 048acd1 · 048acd1
2 parents 2f60b93 + cb1bb70
commit 048acd1
Show file tree

Hide file tree

Showing 10 changed files with 346 additions and 185 deletions.
diff --git a/docs/api/builds.rst b/docs/api/builds.rst
diff --git a/docs/api/core.rst b/docs/api/core.rst
diff --git a/docs/api/doc_builder.rst b/docs/api/doc_builder.rst
diff --git 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
diff --git a/docs/api.rst → docs/api/v1.rst b/docs/api.rst → 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 <http://slumber.readthedocs.io/>`_ 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}