Ship API v3 (#6169)

Ship API v3

Author: humitos

docs/api/index.rst

@@ -11,3 +11,4 @@ from Read the Docs.
     :maxdepth: 3
 
     v2
+    v3

docs/api/v2.rst

@@ -1,22 +1,22 @@
-API v2
-======
+API v2 (deprecated)
+===================
 
 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.
+    A newer and better API v3 is ready to use.
     Some improvements coming in v3 are:
 
-    * Search API
-    * Write access
-    * Simpler URLs which use slugs instead of numeric IDs
+    * Simpler URLs which use slugs
+    * Token based authentication
+    * Import a new project
+    * Activate a version
     * Improved error reporting
 
-    If there are features you would like in v3, please get in touch
-    in the `issue tracker <https://github.com/readthedocs/readthedocs.org/issues>`_.
+    See its full documentation at :doc:`/api/v3`.
 
 
 Authentication and authorization

docs/api/v3.rst

@@ -1,23 +1,10 @@
-:orphan:
-
 API v3
 ======
 
 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.
 
-.. warning::
-
-   APIv3 is currently under development and it's not ready to use yet.
-
-
-.. note::
-
-   If you want to beta test it, please `get in touch`_ with us so we can give you early access.
-
-.. _get in touch: mailto:[email protected]?subject=APIv3%20beta%20test
-
 .. contents:: Table of contents
    :local:
    :backlinks: none
@@ -37,6 +24,11 @@ Token
 The ``Authorization`` HTTP header can be specified with ``Token <your-access-token>``
 to authenticate as a user and have the same permissions that the user itself.
 
+.. note::
+
+   You will find your access Token under
+   `your profile settings <https://readthedocs.org/accounts/tokens/>`_.
+
 
 Session
 ~~~~~~~
@@ -55,6 +47,27 @@ When a user is trying to authenticate via session,
 Resources
 ---------
 
+This section shows all the resources that are currently available in APIv3.
+There are some URL attributes that applies to all of these resources:
+
+:?fields=:
+
+   Specify which fields are going to be returned in the response.
+
+:?omit=:
+
+   Specify which fields are going to be omitted from the response.
+
+:?expand=:
+
+   Some resources allow to expand/add extra fields on their responses (see `Project details <#project-details>`__ for example).
+
+
+.. tip::
+
+   You can browse the full API by accessing its root URL: https://readthedocs.org/api/v3/
+
+
 Projects
 ~~~~~~~~
 
@@ -82,21 +95,8 @@ Projects list
             "results": ["PROJECT"]
         }
 
-    :>json integer count: total number of projects.
-    :>json string next: URI for next set of projects.
-    :>json string previous: URI for previous set of projects.
-    :>json array results: array of ``project`` objects.
-
-    :query string name: name of the project.
-    :query string name__contains: part of the name of the project.
-    :query string slug: slug of the project.
-    :query string slug__contains: part of the slug of the project.
     :query string language: language code as ``en``, ``es``, ``ru``, etc.
-    :query string privacy_level: one of ``public``, ``private``, ``protected``.
     :query string programming_language: programming language code as ``py``, ``js``, etc.
-    :query string repository_type: one of ``git``, ``hg``, ``bzr``, ``svn``.
-
-    :requestheader Authorization: token to authenticate.
 
 
 Project details
@@ -136,10 +136,6 @@ Project details
             },
             "default_version": "stable",
             "default_branch": "master",
-            "privacy_level": {
-                "code": "public",
-                "name": "Public",
-            },
             "subproject_of": null,
             "translation_of": null,
             "urls": {
@@ -174,23 +170,17 @@ Project details
             }
         }
 
-    :>json string name: The name of the project.
-    :>json string slug: The project slug (used in the URL).
-
-    .. TODO: complete the returned data docs once agreed on this.
-
-    :requestheader Authorization: token to authenticate.
-
-    :statuscode 200: Success
-    :statuscode 404: There is no ``Project`` with this slug
+    :query string expand: allows to add/expand some extra fields in the response.
+                          Allowed values are ``active_versions``, ``active_versions.last_build`` and
+                          ``active_versions.last_build.config``. Multiple fields can be passed separated by commas.
 
 
 Project create
 ++++++++++++++
 
 .. http:post:: /api/v3/projects/
 
-    Import a project into Read the Docs.
+    Import a project under authenticated user.
 
     **Example request**:
 
@@ -219,13 +209,7 @@ Project create
 
     **Example response**:
 
-    `See Project details <#project-details>`_
-
-    :requestheader Authorization: token to authenticate.
-
-    :statuscode 201: Created
-    :statuscode 400: Some field is invalid
-
+    `See Project details <#project-details>`__
 
 Project update
 ++++++++++++++
@@ -292,17 +276,8 @@ Versions listing
             "results": ["VERSION"]
         }
 
-    :>json integer count: Total number of Projects.
-    :>json string next: URI for next set of Projects.
-    :>json string previous: URI for previous set of Projects.
-    :>json array results: Array of ``Version`` objects.
-
-    :query integer limit: limit number of object returned
-    :query integer offset: offset from the whole list returned
-    :query boolean active: whether return active versions only
-    :query boolean built: whether return only built version
-
-    :requestheader Authorization: token to authenticate.
+    :query boolean active: return only active versions
+    :query boolean built: return only built versions
 
 
 Version detail
@@ -366,19 +341,23 @@ Version update
 
     **Example request**:
 
+    .. sourcecode:: bash
+
+        $ curl \
+          -X PATCH \
+          -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/version/0.23/ \
+          -H "Content-Type: application/json" \
+          -d @body.json
+
+    The content of ``body.json`` is like,
+
     .. sourcecode:: json
 
         {
             "active": true,
-            "privacy_level": "public"
         }
 
-    :requestheader Authorization: token to authenticate.
-
     :statuscode 204: Updated successfully
-    :statuscode 400: Some field is invalid
-    :statuscode 401: Not valid permissions
-    :statuscode 404: There is no ``Version`` with this slug for this project
 
 
 Builds
@@ -468,22 +447,14 @@ Build details
             }
         }
 
-    :>json integer id: The ID of the build
-    :>json string date: The ISO-8601 datetime of the build.
+    :>json string created: The ISO-8601 datetime when the build was created.
+    :>json string finished: The ISO-8601 datetime when the build has finished.
     :>json integer duration: The length of the build in seconds.
     :>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 builder: The hostname server that built the docs
-    :>json string cold_storage: Whether the build was removed from database and stored externally
-
-    :query boolean include_config: whether or not include the configs used for this build. Default is ``false``
 
-    :requestheader Authorization: token to authenticate.
-
-    :statuscode 200: Success
-    :statuscode 404: There is no ``Build`` with this ID
+    :query string expand: allows to add/expand some extra fields in the response.
+                          Allowed value is ``config``.
 
 
 Builds listing
@@ -511,9 +482,7 @@ Builds listing
         }
 
     :query string commit: commit hash to filter the builds returned by commit
-    :query boolean running: whether or not to filter the builds returned by currently building
-
-    :requestheader Authorization: token to authenticate.
+    :query boolean running: filter the builds that are currently building/running
 
 
 Build triggering
@@ -534,13 +503,15 @@ Build triggering
 
     **Example response**:
 
-    `See Build details <#build-details>`_
+    .. sourcecode:: json
 
-    :requestheader Authorization: token to authenticate.
+        {
+            "build": "{BUILD}",
+            "project": "{PROJECT}",
+            "version": "{VERSION}"
+        }
 
-    :statuscode 202: Accepted
-    :statuscode 400: Some field is invalid
-    :statuscode 401: Not valid permissions
+    :statuscode 202: the build was triggered
 
 
 Subprojects
@@ -693,13 +664,6 @@ Translations listing
             "results": ["PROJECT"]
         }
 
-    :>json integer count: total number of projects.
-    :>json string next: URI for next set of projects.
-    :>json string previous: URI for previous set of projects.
-    :>json array results: array of ``project`` objects.
-
-    :requestheader Authorization: token to authenticate.
-
 
 Redirects
 ~~~~~~~~~
@@ -791,14 +755,21 @@ Redirect create
             "type": "page"
         }
 
+    .. note::
+
+       ``type`` can be one of ``prefix``, ``page``, ``exact``, ``sphinx_html`` and ``sphinx_htmldir``.
+
+       Depending on the ``type`` of the redirect, some fields may not be needed:
+
+       * ``prefix`` type does not require ``to_url``.
+       * ``page`` and ``exact`` types require ``from_url`` and ``to_url``.
+       * ``sphinx_html`` and ``sphinx_htmldir`` types do not require ``from_url`` and ``to_url``.
+
     **Example response**:
 
     `See Redirect details <#redirect-details>`_
 
-    :requestheader Authorization: token to authenticate.
-
-    :statuscode 201: Created
-    :statuscode 400: Some field is invalid
+    :statuscode 201: redirect created successfully
 
 
 Redirect update
@@ -832,12 +803,6 @@ Redirect update
 
     `See Redirect details <#redirect-details>`_
 
-    :requestheader Authorization: token to authenticate.
-
-    :statuscode 200: Success
-    :statuscode 400: Some field is invalid
-
-
 Redirect delete
 ++++++++++++++++
 
@@ -853,9 +818,7 @@ Redirect delete
           -X DELETE \
           -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/1/
 
-    :requestheader Authorization: token to authenticate.
-
-    :statuscode 204: Deleted successfully
+    :statuscode 204: Redirect deleted successfully
 
 
 Environment Variables
@@ -950,10 +913,7 @@ Environment Variable create
 
     `See Environment Variable details <#environmentvariable-details>`_
 
-    :requestheader Authorization: token to authenticate.
-
-    :statuscode 201: Created
-    :statuscode 400: Some field is invalid
+    :statuscode 201: Environment variable created successfully
 
 
 Environment Variable delete
@@ -973,4 +933,4 @@ Environment Variable delete
 
     :requestheader Authorization: token to authenticate.
 
-    :statuscode 204: Deleted successfully
+    :statuscode 204: Environment variable deleted successfully

docs/development/design/apiv3.rst

@@ -70,10 +70,6 @@ Version 1
 
 The first implementation of APIv3 will cover the following aspects:
 
-.. note::
-
-   This is currently implemented and live. Although, it's only for internal testing.
-
 * Authentication
 
   * all endpoints require authentication via ``Authorization:`` request header
@@ -109,6 +105,10 @@ The first implementation of APIv3 will cover the following aspects:
 Version 2
 +++++++++
 
+.. note::
+
+   This is currently implemented and live.
+
 Second iteration will polish issues found from the first step,
 and add new endpoints to allow *import a project and configure it*
 without the needed of using the WebUI as a main goal.
@@ -124,6 +124,7 @@ This iteration will include:
 * Edit Project attributes ("Settings" and "Advanced settings-Global settings" in the WebUI)
 * Trigger Build for default version
 * Allow CRUD for Redirect, Environment Variables and Notifications (``WebHook`` and ``EmailHook``)
+* Create/Delete a Project as subproject of another Project
 * Documentation