Initial structure for APIv3 (#5356)

Initial structure for APIv3

docs/api/v3.rst

@@ -14,15 +14,7 @@ Authentication and authorization
 --------------------------------
 
 Requests to the Read the Docs public API are for public and private information.
-Some listing endpoints and some detailed ones are allowed to access without being authenticated.
-Although, all endpoints that perform non-readonly operations, require authentication.
-
-
-No authentication
-~~~~~~~~~~~~~~~~~
-
-Some endpoints on read-only requests won't require any kind of authentication.
-Most of them are detailed information of specific listings for a particular object.
+All endpoints require authentication.
 
 
 Token
@@ -35,6 +27,10 @@ and have the same permissions that the user itself.
 Session
 ~~~~~~~
 
+.. warning::
+
+   Authentication via session is not enabled yet.
+
 Session authentication is allowed on very specific endpoints,
 to allow hitting the API when reading documentation.
 
@@ -77,13 +73,16 @@ Projects list
     :>json string previous: URI for previous set of projects.
     :>json array results: array of ``project`` objects.
 
-    :query string privacy_level: one of ``public``, ``private``, ``protected``.
+    :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_url: URL of the repository.
     :query string repository_type: one of ``git``, ``hg``, ``bzr``, ``svn``.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Project details
@@ -97,7 +96,7 @@ Project details
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/
 
     **Example response**:
 
@@ -168,9 +167,7 @@ Project details
 
     .. TODO: complete the returned data docs once agreed on this.
 
-    :query boolean inactive_versions: whether or not include inactive versions.
-
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 200: Success
     :statuscode 404: There is no ``Project`` with this slug
@@ -199,7 +196,7 @@ Versions listing
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/versions/
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/
 
     **Example response**:
 
@@ -225,7 +222,7 @@ Versions listing
     :query boolean active: whether return active versions only
     :query boolean built: whether return only built version
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Version detail
@@ -239,7 +236,7 @@ Version detail
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/versions/stable/
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/stable/
 
     **Example response**:
 
@@ -287,7 +284,7 @@ Version detail
     :>json string last_build: Build object representing the last build of this version
     :>json array downloads: URLs to downloads of this version's documentation
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 200: Success
     :statuscode 404: There is no ``Version`` with this slug for this project
@@ -309,11 +306,7 @@ Version edit
             "privacy_level": "public"
         }
 
-    **Example response**:
-
-    `See Version details <#version-detail>`_
-
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 204: Edited sucessfully
     :statuscode 400: Some field is invalid
@@ -344,7 +337,7 @@ Build details
 
     .. sourcecode:: bash
 
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/8592686/?include_config=true
+        $ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config
 
     **Example response**:
 
@@ -422,29 +415,12 @@ Build details
 
     :query boolean include_config: whether or not include the configs used for this build. Default is ``false``
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
     :statuscode 200: Success
     :statuscode 404: There is no ``Build`` with this ID
 
 
-.. http:get:: /api/v3/projects/(str:project_slug)/builds/latest/
-
-    Retrieve details for latest build on this project.
-
-    **Example request**:
-
-    .. sourcecode:: bash
-
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/latest/
-
-    **Example response**:
-
-    `See Build details <#build-details>`_
-
-    :requestheader Authorization: optional token to authenticate.
-
-
 Builds listing
 ++++++++++++++
 
@@ -472,102 +448,28 @@ 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: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Build triggering
 ++++++++++++++++
 
 
-.. http:post:: /api/v3/projects/(string:project_slug)/builds/
-
-    Trigger a new build for this project.
-
-    **Example request**:
-
-    .. sourcecode:: json
+.. http:post:: /api/v3/projects/(string:project_slug)/versions/(string:version_slug)/builds/
 
-        {
-            "version": "latest",
-        }
+    Trigger a new build for the ``version_slug`` version of this project.
 
     **Example response**:
 
     `See Build details <#build-details>`_
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
-    :statuscode 201: Created sucessfully
+    :statuscode 202: Accepted
     :statuscode 400: Some field is invalid
     :statuscode 401: Not valid permissions
 
 
-Build commands listing
-++++++++++++++++++++++
-
-.. http:get:: /api/v3/projects/(str:project_slug)/builds/(int:build_id)/commands/
-
-    Retrieve build command list of a single build.
-
-    **Example request**:
-
-    .. sourcecode:: bash
-
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/719263915/commands/
-
-    **Example response**:
-
-    .. sourcecode:: json
-
-        {
-            "count": 15,
-            "next": "/api/v3/projects/pip/builds/719263915/commands/?limit=10&offset=10",
-            "previous": null,
-            "results": ["BUILDCOMMAND"]
-        }
-
-    :requestheader Authorization: optional token to authenticate.
-
-
-Build command details
-+++++++++++++++++++++
-
-.. http:get:: /api/v3/projects/(str:project_slug)/builds/(int:build_id)/commands/(int:buildcommand_id)
-
-    Retrieve build command detail.
-
-    **Example request**:
-
-    .. sourcecode:: bash
-
-        $ curl https://readthedocs.org/api/v3/projects/pip/builds/719263915/commands/9182639172/
-
-    **Example response**:
-
-    .. sourcecode:: json
-
-        {
-            "id": 9182639172,
-            "build": 719263915,
-            "project": "pip",
-            "version": "stable",
-            "created": "2018-06-19T15:15:59+00:00",
-            "finished": "2018-06-19T15:16:58+00:00",
-            "duration": 59,
-            "command": "cat docs/config.py",
-            "output": "...",
-            "exit_code": 0,
-            "links": {
-                "self": "/api/v3/projects/pip/builds/719263915/commands/9182639172/",
-                "build": "/api/v3/projects/pip/builds/719263915/",
-                "version": "/api/v3/projects/pip/versions/stable/",
-                "project": "/api/v3/projects/pip/"
-            }
-        }
-
-    :requestheader Authorization: optional token to authenticate.
-
-
 Users
 ~~~~~
 
@@ -590,36 +492,16 @@ User detail
     .. sourcecode:: json
 
         {
-            "id": 25,
             "username": "humitos",
             "created": "2008-10-23T18:12:31+00:00",
-            "last_login": "2010-10-23T18:12:31+00:00",
-            "first_name": "Manuel",
-            "last_name": "Kaufmann",
-            "email": "humitos@readthedocs.org",
-            "links": {
-                "self": "/api/v3/users/humitos/",
-                "projects": "/api/v3/projects/?user=humitos"
-            }
+            "last_login": "2010-10-23T18:12:31+00:00"
         }
 
-    .. TODO: considering that ``/api/v3/projects/`` will return only
-       the projects for the authenticated user, the ``projects`` link
-       here won't work.
-
-       On the other hand, ``/api/v3/projects/all/?user=humitos`` can't
-       be used because we will be mixing ``all`` as project slug with
-       our endpoint URL.
-
-    :>json integer id: ID for the user on the database.
     :>json string username: username for the user.
     :>json string created: date and time when the user was created.
     :>json string last_login: date and time for last time this user was logged in.
-    :>json string first_name: first name of the user.
-    :>json string last_name: last name of the user.
-    :>json string email: email of the user.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 User listing
@@ -652,7 +534,7 @@ User listing
     :>json string previous: URI for previous set of users.
     :>json array results: array of ``user`` objects.
 
-    :requestheader Authorization: optional token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Subprojects
@@ -688,7 +570,7 @@ Subprojects listing
     :>json string previous: URI for previous set of projects.
     :>json array results: array of ``project`` objects.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.
 
 
 Translations
@@ -724,4 +606,4 @@ Translations listing
     :>json string previous: URI for previous set of projects.
     :>json array results: array of ``project`` objects.
 
-    :requestheader Authorization: required token to authenticate.
+    :requestheader Authorization: token to authenticate.

pytest.ini

@@ -15,3 +15,6 @@ filterwarnings =
     ignore:Pagination may yield inconsistent results with an unordered object_list.*:django.core.paginator.UnorderedObjectListWarning
     # docutils
     ignore:'U' mode is deprecated:DeprecationWarning
+
+    # rest_framework_extensions.routers raises these
+    ignore::rest_framework.RemovedInDRF311Warning

readthedocs/restapi/client.py → readthedocs/api/v2/client.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Simple client to access our API with Slumber credentials."""
 
 import logging

readthedocs/restapi/permissions.py → readthedocs/api/v2/permissions.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Defines access permissions for the API."""
 
 from rest_framework import permissions

readthedocs/restapi/serializers.py → readthedocs/api/v2/serializers.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Defines serializers for each of our models."""
 
 from allauth.socialaccount.models import SocialAccount

readthedocs/restapi/signals.py → readthedocs/api/v2/signals.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """We define custom Django signals to trigger when a footer is rendered."""
 
 import django.dispatch

readthedocs/restapi/urls.py → readthedocs/api/v2/urls.py

@@ -1,18 +1,17 @@
-# -*- coding: utf-8 -*-
-
 """Define routes between URL paths and views/endpoints."""
 
 from django.conf import settings
 from django.conf.urls import include, url
 from rest_framework import routers
 
-from readthedocs.constants import pattern_opts
-from readthedocs.restapi.views import (
+from readthedocs.api.v2.views import (
     core_views,
     footer_views,
     integrations,
     task_views,
 )
+from readthedocs.constants import pattern_opts
+from readthedocs.sphinx_domains.api import SphinxDomainAPIView
 
 from .views.model_views import (
     BuildCommandViewSet,
@@ -25,7 +24,6 @@
     SocialAccountViewSet,
     VersionViewSet,
 )
-from readthedocs.sphinx_domains.api import SphinxDomainAPIView
 
 
 router = routers.DefaultRouter()

readthedocs/restapi/utils.py → readthedocs/api/v2/utils.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Utility functions that are used by both views and celery tasks."""
 
 import logging