API filtering improvements

docs/api/v2.rst

@@ -51,19 +51,29 @@ Project list
 
     Retrieve a list of all Read the Docs projects.
 
+    **Example request**:
+
+    .. sourcecode:: bash
+
+        $ curl https://readthedocs.org/api/v2/project/?slug=pip
+
+    **Example response**:
+
     .. sourcecode:: js
 
         {
-            "count": 10000,
-            "next": "http://readthedocs.org/api/v2/project/?page=2",
+            "count": 1,
+            "next": null,
             "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.
+    :>json array results: Array of ``Project`` objects.
+
+    :query string slug: Narrow the results by matching the exact project slug
 
 Project details
 +++++++++++++++
@@ -118,37 +128,12 @@ Project versions
     .. 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},
-                },
-                ...
-            ]
+            "versions": [VERSION, VERSION, ...]
         }
 
+    :>json array versions: Version objects for the given ``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.
-
+    See the :ref:`Version detail <api-version-detail>` call for the format of the ``Version`` object.
 
 Versions
 ~~~~~~~~
@@ -165,22 +150,26 @@ Version list
 
 .. http:get::  /api/v2/version/
 
-    Retrieve a list of all Versions for all projects (10 at a time).
+    Retrieve a list of all Versions for all projects
 
     .. sourcecode:: js
 
         {
             "count": 1000,
             "previous": null,
             "results": [VERSIONS],
-            "next": "http://readthedocs.org/api/v2/version/?limit=10&offset=10"
+            "next": "https://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.
+    :>json array results: Array of ``Version`` objects.
+
+    :query string project__slug: Narrow to the versions for a specific ``Project``
+
+.. _api-version-detail:
 
 Version detail
 ++++++++++++++
@@ -232,11 +221,39 @@ 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 list
+++++++++++
+
+.. http:get::  /api/v2/build/
+
+    Retrieve details of builds ordered by most recent first
+
+    **Example request**:
+
+    .. sourcecode:: bash
+
+        $ curl https://readthedocs.org/api/v2/build/?project__slug=pip
+
+    **Example response**:
+
+    .. sourcecode:: js
+
+        {
+            "count": 100,
+            "next": null,
+            "previous": null,
+            "results": [BUILDS]
+        }
+
+    :>json string next: URI for next set of Builds.
+    :>json string previous: URI for previous set of Builds.
+    :>json integer count: Total number of Builds.
+    :>json array results: Array of ``Build`` objects.
+
+    :query string project__slug: Narrow to builds for a specific ``Project``
 
 Build detail
-++++++++++++++
+++++++++++++
 
 .. http:get::  /api/v2/build/(int:id)/
 

readthedocs/restapi/views/model_views.py

@@ -91,6 +91,7 @@ class ProjectViewSet(UserSelectViewSet):
     admin_serializer_class = ProjectAdminSerializer
     model = Project
     pagination_class = api_utils.ProjectPagination
+    filter_fields = ('slug',)
 
     @decorators.detail_route()
     def valid_versions(self, request, **kwargs):
@@ -232,6 +233,7 @@ class VersionViewSet(UserSelectViewSet):
     serializer_class = VersionSerializer
     admin_serializer_class = VersionAdminSerializer
     model = Version
+    filter_fields = ('project__slug',)
 
 
 class BuildViewSetBase(UserSelectViewSet):
@@ -240,6 +242,7 @@ class BuildViewSetBase(UserSelectViewSet):
     serializer_class = BuildSerializer
     admin_serializer_class = BuildAdminSerializer
     model = Build
+    filter_fields = ('project__slug',)
 
 
 class BuildViewSet(SettingsOverrideObject):

readthedocs/settings/base.py

@@ -356,6 +356,7 @@ def USE_PROMOS(self):  # noqa
         'field_name_limit': 50,
     }
     REST_FRAMEWORK = {
+        'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',),
         'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',  # NOQA
         'PAGE_SIZE': 10,
     }

requirements/pip.txt

@@ -24,6 +24,9 @@ django-extensions==2.0.7
 # djangorestframework 3.7.x drops support for django 1.9.x
 djangorestframework==3.6.4
 
+# Filtering for the REST API
+django-filter==1.1.0
+
 django-vanilla-views==1.0.5
 jsonfield==2.0.2