diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 3364b0b74f0..bb043a9f0b7 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,5 +1,5 @@ [rstcheck] -ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post +ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete ignore_roles=djangosetting,setting,featureflags,buildpyversions # This error needs to be ignored for now # See: https://github.com/myint/rstcheck/issues/19 diff --git a/docs/api/v3.rst b/docs/api/v3.rst index 001bcc7c98e..c498f485b32 100644 --- a/docs/api/v3.rst +++ b/docs/api/v3.rst @@ -12,6 +12,18 @@ and HTTP response status codes are to designate success and failure. 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:support@readthedocs.org?subject=APIv3%20beta%20test + +.. contents:: Table of contents + :local: + :backlinks: none + :depth: 3 + + Authentication and authorization -------------------------------- @@ -22,8 +34,8 @@ All endpoints require authentication. Token ~~~~~ -The ``Authorization`` HTTP header can be specified with a ``Token`` to authenticate as a user -and have the same permissions that the user itself. +The ``Authorization`` HTTP header can be specified with ``Token `` +to authenticate as a user and have the same permissions that the user itself. Session @@ -108,7 +120,6 @@ Project details "id": 12345, "name": "Pip", "slug": "pip", - "description": "Pip Installs Packages.", "created": "2010-10-23T18:12:31+00:00", "modified": "2018-12-11T07:21:11+00:00", "language": { @@ -133,7 +144,7 @@ Project details "translation_of": null, "urls": { "documentation": "http://pip.pypa.io/en/stable/", - "project": "https://pip.pypa.io/" + "home": "https://pip.pypa.io/" }, "tags": [ "disutils", @@ -143,29 +154,28 @@ Project details "virtualenv" ], "users": [ - "dstufft", - "pmoore", - "xafer", - "pradyunsg" + { + "username": "dstufft" + } ], "active_versions": { "stable": "{VERSION}", "latest": "{VERSION}", "19.0.2": "{VERSION}" }, - "links": { - "self": "/api/v3/projects/pip/", - "users": "/api/v3/projects/pip/users/", + "_links": { + "_self": "/api/v3/projects/pip/", "versions": "/api/v3/projects/pip/versions/", "builds": "/api/v3/projects/pip/builds/", "subprojects": "/api/v3/projects/pip/subprojects/", + "superproject": "/api/v3/projects/pip/superproject/", + "redirects": "/api/v3/projects/pip/redirects/", "translations": "/api/v3/projects/pip/translations/" } } :>json string name: The name of the project. :>json string slug: The project slug (used in the URL). - :>json string description: An RST description of the project .. TODO: complete the returned data docs once agreed on this. @@ -175,6 +185,47 @@ Project details :statuscode 404: There is no ``Project`` with this slug +Project create +++++++++++++++ + +.. http:post:: /api/v3/projects/ + + Import a project into Read the Docs. + + **Example request**: + + .. sourcecode:: bash + + $ curl \ + -X POST \ + -H "Authorization: Token " https://readthedocs.org/api/v3/projects/ \ + -H "Content-Type: application/json" \ + -d @body.json + + The content of ``body.json`` is like, + + .. sourcecode:: json + + { + "name": "Test Project", + "repository": { + "url": "https://github.com/readthedocs/template", + "type": "git" + }, + "homepage": "http://template.readthedocs.io/", + "programming_language": "py", + "language": "es" + } + + **Example response**: + + `See Project details <#project-details>`_ + + :requestheader Authorization: token to authenticate. + + :statuscode 201: Created + :statuscode 400: Some field is invalid + Versions ~~~~~~~~ @@ -183,6 +234,7 @@ Versions are different versions of the same project documentation. The versions for a given project can be viewed in a project's version page. For example, here is the `Pip project's version page`_. +See :doc:`/versions` for more information. .. _Pip project's version page: https://readthedocs.org/projects/pip/versions/ @@ -216,9 +268,6 @@ Versions listing :>json string previous: URI for previous set of Projects. :>json array results: Array of ``Version`` objects. - .. TODO: instead of an array, this could potentially be a - dictionary with the slug as the key and a VERSION as value. - :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 @@ -253,10 +302,6 @@ Version detail "built": true, "active": true, "uploaded": true, - "privacy_level": { - "code": "public", - "name": "Public", - }, "type": "tag", "last_build": "{BUILD}", "downloads": { @@ -268,8 +313,8 @@ Version detail "documentation": "https://pip.pypa.io/en/stable/", "vcs": "https://github.com/pypa/pip/tree/19.0.2" }, - "links": { - "self": "/api/v3/projects/pip/versions/stable/", + "_links": { + "_self": "/api/v3/projects/pip/versions/stable/", "builds": "/api/v3/projects/pip/versions/stable/builds/", "project": "/api/v3/projects/pip/" } @@ -292,8 +337,8 @@ Version detail :statuscode 404: There is no ``Version`` with this slug for this project -Version edit -++++++++++++ +Version update +++++++++++++++ .. http:patch:: /api/v3/projects/(string:project_slug)/version/(string:version_slug)/ @@ -324,6 +369,7 @@ Frequently this happens automatically via a web hook but can be triggered manual Builds can be viewed in the build page for a project. For example, here is `Pip's build page`_. +See :doc:`/builds` for more information. .. _Pip's build page: https://readthedocs.org/projects/pip/builds/ @@ -359,8 +405,6 @@ Build details "success": true, "error": null, "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30", - "builder": "build03", - "cold_storage": false, "config": { "version": "1", "formats": [ @@ -397,11 +441,10 @@ Build details "recursive": true } }, - "links": { - "self": "/api/v3/projects/pip/builds/8592686/", + "_links": { + "_self": "/api/v3/projects/pip/builds/8592686/", "project": "/api/v3/projects/pip/", - "version": "/api/v3/projects/pip/versions/latest/", - "commands": "/api/v3/projects/pip/builds/8592686/commands/" + "version": "/api/v3/projects/pip/versions/latest/" } } @@ -434,7 +477,7 @@ Builds listing .. sourcecode:: bash - $ curl https://readthedocs.org/api/v3/projects/pip/builds/ + $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/builds/ **Example response**: @@ -461,6 +504,14 @@ Build triggering Trigger a new build for the ``version_slug`` version of this project. + **Example request**: + + .. sourcecode:: bash + + $ curl \ + -X POST \ + -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/versions/latest/builds/ + **Example response**: `See Build details <#build-details>`_ @@ -472,53 +523,67 @@ Build triggering :statuscode 401: Not valid permissions -Users -~~~~~ +Subprojects +~~~~~~~~~~~ -User detail -+++++++++++ +Projects can be configured in a nested manner, +by configuring a project as a subproject of another project. +This allows for documentation projects to share a search index and a namespace or custom domain, +but still be maintained independently. +See :doc:`/subprojects` for more information. +Subprojects listing ++++++++++++++++++++ -.. http:get:: /api/v3/users/(str:username) - Retrieve details of a single user. +.. http:get:: /api/v3/projects/(str:project_slug)/subprojects/ + + Retrieve a list of all sub-projects for a project. **Example request**: .. sourcecode:: bash - $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/users/ + $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/subprojects/ **Example response**: .. sourcecode:: json { - "username": "humitos", - "created": "2008-10-23T18:12:31+00:00", - "last_login": "2010-10-23T18:12:31+00:00" + "count": 25, + "next": "/api/v3/projects/pip/subprojects/?limit=10&offset=10", + "previous": null, + "results": ["PROJECT"] } - :>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 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. -User listing -++++++++++++ +Translations +~~~~~~~~~~~~ + +Translations are the same version of a Project in a different language. +See :doc:`/localization` for more information. + +Translations listing +++++++++++++++++++++ -.. http:get:: /api/v3/projects/(str:project_slug)/users/ +.. http:get:: /api/v3/projects/(str:project_slug)/translations/ - Retrieve list of users for a project. + Retrieve a list of all translations for a project. **Example request**: .. sourcecode:: bash - $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/users/ + $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/translations/ **Example response**: @@ -526,86 +591,289 @@ User listing { "count": 25, - "next": "/api/v3/projects/pip/users/limit=10&offset=10", + "next": "/api/v3/projects/pip/translations/?limit=10&offset=10", "previous": null, - "results": ["USER"] + "results": ["PROJECT"] } - :>json integer count: total number of users. - :>json string next: URI for next set of users. - :>json string previous: URI for previous set of users. - :>json array results: array of ``user`` objects. + :>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. -Subprojects -~~~~~~~~~~~ +Redirects +~~~~~~~~~ -Subprojects listing -+++++++++++++++++++ +Redirects allow the author to redirect an old URL of the documentation to a new one. +This is useful when pages are moved around in the structure of the documentation set. +See :doc:`/user-defined-redirects` for more information. -.. http:get:: /api/v3/projects/(str:project_slug)/subprojects/ +Redirect details +++++++++++++++++ - Retrieve a list of all sub-projects for a project. +.. http:get:: /api/v3/projects/(str:project_slug)/redirects/(int:redirect_id)/ - **Example request**: + Retrieve details of a single redirect for a project. + + **Example request** .. sourcecode:: bash - $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/subprojects/ + $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/redirects/1/ - **Example response**: + **Example response** + + .. sourcecode:: json + + { + "pk": 1, + "created": "2019-04-29T10:00:00Z", + "modified": "2019-04-29T12:00:00Z", + "project": "pip", + "from_url": "/docs/", + "to_url": "/documentation/", + "type": "page", + "_links": { + "_self": "/api/v3/projects/pip/redirects/1/", + "project": "/api/v3/projects/pip/" + } + } + +Redirects listing ++++++++++++++++++ + +.. http:get:: /api/v3/projects/(str:project_slug)/redirects/ + + Retrieve list of all the redirects for this project. + + **Example request** + + .. sourcecode:: bash + + $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/redirects/ + + **Example response** .. sourcecode:: json { "count": 25, - "next": "/api/v3/projects/pip/subprojects/?limit=10&offset=10", + "next": "/api/v3/projects/pip/redirects/?limit=10&offset=10", "previous": null, - "results": ["PROJECT"] + "results": ["REDIRECT"] } - :>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. +Redirect create ++++++++++++++++ - :requestheader Authorization: token to authenticate. +.. http:post:: /api/v3/projects/pip/redirects/ + Create a redirect for this project. -Translations -~~~~~~~~~~~~ + **Example request**: -Translations listing -++++++++++++++++++++ + .. sourcecode:: bash + $ curl \ + -X POST \ + -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/redirects/ \ + -H "Content-Type: application/json" \ + -d @body.json -.. http:get:: /api/v3/projects/(str:project_slug)/translations/ + The content of ``body.json`` is like, - Retrieve a list of all translations for a project. + .. sourcecode:: json + + { + "from_url": "/docs/", + "to_url": "/documentation/", + "type": "page" + } + + **Example response**: + + `See Redirect details <#redirect-details>`_ + + :requestheader Authorization: token to authenticate. + + :statuscode 201: Created + :statuscode 400: Some field is invalid + + +Redirect update ++++++++++++++++ + +.. http:put:: /api/v3/projects/(str:project_slug)/redirects/(int:redirect_id)/ + + Update a redirect for this project. **Example request**: .. sourcecode:: bash - $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/translations/ + $ curl \ + -X PUT \ + -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/redirects/1/ \ + -H "Content-Type: application/json" \ + -d @body.json + + The content of ``body.json`` is like, + + .. sourcecode:: json + + { + "from_url": "/docs/", + "to_url": "/documentation.html", + "type": "page" + } **Example response**: + `See Redirect details <#redirect-details>`_ + + :requestheader Authorization: token to authenticate. + + :statuscode 200: Success + :statuscode 400: Some field is invalid + + +Redirect delete +++++++++++++++++ + +.. http:delete:: /api/v3/projects/(str:project_slug)/redirects/(int:redirect_id)/ + + Delete a redirect for this project. + + **Example request**: + + .. sourcecode:: bash + + $ curl \ + -X DELETE \ + -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/redirects/1/ + + :requestheader Authorization: token to authenticate. + + :statuscode 204: Deleted successfully + + +Environment Variables +~~~~~~~~~~~~~~~~~~~~~ + +Environment Variables are variables that you can define for your project. +These variables are used in the build process when building your documentation. +They are useful to define secrets in a safe way that can be used by your documentation to build properly. +See :doc:`/guides/environment-variables` + + +Environment Variable details +++++++++++++++++++++++++++++ + +.. http:get:: /api/v3/projects/(str:project_slug)/environmentvariables/(int:environmentvariable_id)/ + + Retrieve details of a single environment variable for a project. + + **Example request** + + .. sourcecode:: bash + + $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/ + + **Example response** + + .. sourcecode:: json + + { + "_links": { + "_self": "https://readthedocs.org/api/v3/projects/project/environmentvariables/1/", + "project": "https://readthedocs.org/api/v3/projects/project/" + }, + "created": "2019-04-29T10:00:00Z", + "modified": "2019-04-29T12:00:00Z", + "pk": 1, + "project": "project", + "name": "ENVVAR" + } + +Environment Variables listing ++++++++++++++++++++++++++++++ + +.. http:get:: /api/v3/projects/(str:project_slug)/environmentvariables/ + + Retrieve list of all the environment variables for this project. + + **Example request** + + .. sourcecode:: bash + + $ curl -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/environmentvariables/ + + **Example response** + .. sourcecode:: json { - "count": 25, - "next": "/api/v3/projects/pip/translations/?limit=10&offset=10", + "count": 15, + "next": "/api/v3/projects/pip/environmentvariables/?limit=10&offset=10", "previous": null, - "results": ["PROJECT"] + "results": ["ENVIRONMENTVARIABLE"] } - :>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. +Environment Variable create ++++++++++++++++++++++++++++ + +.. http:post:: /api/v3/projects/pip/environmentvariables/ + + Create an environment variable for this project. + + **Example request**: + + .. sourcecode:: bash + + $ curl \ + -X POST \ + -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/environmentvariables/ \ + -H "Content-Type: application/json" \ + -d @body.json + + The content of ``body.json`` is like, + + .. sourcecode:: json + + { + "name": "MYVAR", + "value": "My secret value" + } + + **Example response**: + + `See Environment Variable details <#environmentvariable-details>`_ + + :requestheader Authorization: token to authenticate. + + :statuscode 201: Created + :statuscode 400: Some field is invalid + + +Environment Variable delete ++++++++++++++++++++++++++++ + +.. http:delete:: /api/v3/projects/(str:project_slug)/environmentvariables/(int:environmentvariable_id)/ + + Delete an environment variable for this project. + + **Example request**: + + .. sourcecode:: bash + + $ curl \ + -X DELETE \ + -H "Authorization: Token " https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/ :requestheader Authorization: token to authenticate. + + :statuscode 204: Deleted successfully diff --git a/readthedocs/api/v3/serializers.py b/readthedocs/api/v3/serializers.py index 7f5efa69943..f71d816cb43 100644 --- a/readthedocs/api/v3/serializers.py +++ b/readthedocs/api/v3/serializers.py @@ -16,13 +16,10 @@ class UserSerializer(FlexFieldsModelSerializer): - created = serializers.DateTimeField(source='date_joined') - class Meta: model = User fields = [ 'username', - 'created', ] diff --git a/readthedocs/api/v3/tests/responses/projects-detail.json b/readthedocs/api/v3/tests/responses/projects-detail.json index e36c5f7d000..dafbee8d1b5 100644 --- a/readthedocs/api/v3/tests/responses/projects-detail.json +++ b/readthedocs/api/v3/tests/responses/projects-detail.json @@ -97,7 +97,6 @@ }, "users": [ { - "created": "2019-04-29T10:00:00Z", "username": "testuser" } ] diff --git a/readthedocs/api/v3/tests/responses/projects-list.json b/readthedocs/api/v3/tests/responses/projects-list.json index ccb9ab0390b..2313c2247cb 100644 --- a/readthedocs/api/v3/tests/responses/projects-list.json +++ b/readthedocs/api/v3/tests/responses/projects-list.json @@ -43,7 +43,6 @@ ], "users": [ { - "created": "2019-04-29T10:00:00Z", "username": "testuser" } ], diff --git a/readthedocs/api/v3/tests/responses/projects-list_POST.json b/readthedocs/api/v3/tests/responses/projects-list_POST.json index 2f402a657d4..20ea4ce9edc 100644 --- a/readthedocs/api/v3/tests/responses/projects-list_POST.json +++ b/readthedocs/api/v3/tests/responses/projects-list_POST.json @@ -44,7 +44,6 @@ }, "users": [ { - "created": "2019-04-29T10:00:00Z", "username": "testuser" } ] diff --git a/readthedocs/api/v3/tests/responses/projects-subprojects-list.json b/readthedocs/api/v3/tests/responses/projects-subprojects-list.json index 2a43314f0d6..e5df1382523 100644 --- a/readthedocs/api/v3/tests/responses/projects-subprojects-list.json +++ b/readthedocs/api/v3/tests/responses/projects-subprojects-list.json @@ -78,7 +78,6 @@ }, "users": [ { - "created": "2019-04-29T10:00:00Z", "username": "testuser" } ] diff --git a/readthedocs/api/v3/tests/responses/projects-superproject.json b/readthedocs/api/v3/tests/responses/projects-superproject.json index 081e8066814..865cf46f812 100644 --- a/readthedocs/api/v3/tests/responses/projects-superproject.json +++ b/readthedocs/api/v3/tests/responses/projects-superproject.json @@ -48,7 +48,6 @@ }, "users": [ { - "created": "2019-04-29T10:00:00Z", "username": "testuser" } ] diff --git a/readthedocs/api/v3/tests/responses/projects-versions-builds-list_POST.json b/readthedocs/api/v3/tests/responses/projects-versions-builds-list_POST.json index dcbdb70eeeb..6f099147022 100644 --- a/readthedocs/api/v3/tests/responses/projects-versions-builds-list_POST.json +++ b/readthedocs/api/v3/tests/responses/projects-versions-builds-list_POST.json @@ -69,7 +69,6 @@ }, "users": [ { - "created": "2019-04-29T10:00:00Z", "username": "testuser" } ]