From db7edc6d2995661efd3ceee8052ba34c5e389c78 Mon Sep 17 00:00:00 2001 From: David Fischer Date: Tue, 19 Jun 2018 14:56:24 -0700 Subject: [PATCH 1/5] Add documentation for APIv2 - This is a pure docs PR, no code changes - Move internal class API to "developer-interface" folder - Move APIv1 into a folder and add APIv2 --- docs/api/index.rst | 31 +- docs/{api.rst => api/v1.rst} | 21 +- docs/api/v2.rst | 338 ++++++++++++++++++ docs/builds.rst | 2 +- docs/{api => developer-interface}/builds.rst | 0 docs/{api => developer-interface}/core.rst | 0 .../doc_builder.rst | 0 docs/developer-interface/index.rst | 14 + .../{api => developer-interface}/projects.rst | 0 .../vcs_support.rst | 0 docs/index.rst | 4 +- 11 files changed, 389 insertions(+), 21 deletions(-) rename docs/{api.rst => api/v1.rst} (96%) create mode 100644 docs/api/v2.rst rename docs/{api => developer-interface}/builds.rst (100%) rename docs/{api => developer-interface}/core.rst (100%) rename docs/{api => developer-interface}/doc_builder.rst (100%) create mode 100644 docs/developer-interface/index.rst rename docs/{api => developer-interface}/projects.rst (100%) rename docs/{api => developer-interface}/vcs_support.rst (100%) diff --git a/docs/api/index.rst b/docs/api/index.rst index 1d78be1b363..cd0c4ad7b4c 100644 --- 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 we 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.rst b/docs/api/v1.rst similarity index 96% rename from docs/api.rst rename to docs/api/v1.rst index d1204960a73..a8c9e047130 100644 --- a/docs/api.rst +++ b/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 `_ 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} diff --git a/docs/api/v2.rst b/docs/api/v2.rst new file mode 100644 index 00000000000..65e94f01425 --- /dev/null +++ b/docs/api/v2.rst @@ -0,0 +1,338 @@ +API v2 +====== + +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. + Some improvements coming in v3 are: + + * Write access + * Simpler URLs which use slugs instead of numeric IDs + * Improved error reporting + + If there are features you would like in v3, please get in touch + in the `issue tracker `_. + + +Authentication and authorization +-------------------------------- + +Requests to the Read the Docs public API are for public information only +and do not require any authentication. + + +Resources +--------- + +Projects +~~~~~~~~ + +Projects are the main building block of Read the Docs. +Projects are built when there are changes to the code +and the resulting documentation is hosted and served by Read the Docs. + +As an example, this documentation is part of the `Docs project`_ +which has documentation at https://docs.readthedocs.io. + +You can always view your Read the Docs projects in your `project dashboard`_. + +.. _Docs project: https://readthedocs.org/projects/docs/ +.. _project dashboard: https://readthedocs.org/dashboard/ + +Project search +++++++++++++++ + +.. tip:: + + This API is in need of simplifying for end users. + Largely this endpoint should be used only to get the Project ID + which is used in other API calls. + +.. http:get:: /api/v2/search/project/?q={query} + + Search for projects by name or description. + Results are returned in order of the best match. + + .. sourcecode:: js + + { + "results": { + "hits": { + "hits": [ + { + "fields": { + // Returned fields + }, + "_id": "13" // Project ID + }, + ], + }, + "facets": { + // Facet Data + }, + "took": 15, + "timed_out": false, + } + } + + :>json array results: An array of matching results + +Project list +++++++++++++ + +.. http:get:: /api/v2/project/ + + Retrieve a list of all Read the Docs projects. + + .. sourcecode:: js + + { + "count": 10000, + "next": "http://readthedocs.org/api/v2/project/?page=2", + "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. + +Project details ++++++++++++++++ + +.. http:get:: /api/v2/project/{id}/ + + Retrieve details of a single project. + + .. sourcecode:: js + + { + "id": 6, + "name": "Pip", + "slug": "pip", + "programming_language": "py", + "default_version": "stable", + "default_branch": "master", + "repo_type": "git", + "repo": "https://github.com/pypa/pip", + "description": "Pip Installs Packages.", + "language": "en", + "documentation_type": "sphinx_htmldir", + "canonical_url": "http://pip.pypa.io/en/stable/", + "users": [USERS] + } + + + :>json integer id: The ID of the project + :>json string name: The name of the project. + :>json string slug: The project slug (used in the URL). + :>json string programming_language: The programming language of the project (eg. "py", "js") + :>json string default_version: The default version of the project (eg. "latest", "stable", "v3") + :>json string default_branch: The default version control branch + :>json string repo_type: Version control repository of the project + :>json string repo: The repository URL for the project + :>json string description: An RST description of the project + :>json string language: The language code of this project + :>json string documentation_type: An RST description of the project + :>json string canonical_url: The canonical URL of the default docs + :>json array users: Array of ``User`` IDs who are maintainers of the project. + +Project versions +++++++++++++++++ + +.. http:get:: /api/v2/project/{id}/active_versions/ + + Retrieve a list of active versions (eg. "latest", "stable", "v1.x") for a single project. + + .. 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}, + }, + ... + ] + } + + + :>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. + + +Versions +~~~~~~~~ + +Versions are different versions of the same project documentation + +The versions for a given project can be viewed in a project's version screen. +For example, here is the `Pip project's version screen`_. + +.. _Pip project's version screen: https://readthedocs.org/projects/pip/versions/ + +Version list +++++++++++++ + +.. http:get:: /api/v2/version/ + + Retrieve a list of all Versions for all projects (10 at a time). + + .. sourcecode:: js + + { + "count": 1000, + "previous": null, + "results": [VERSIONS], + "next": "http://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. + +Version detail +++++++++++++++ + +.. http:get:: /api/v2/version/{id}/ + + Retrieve details of a single version. + + .. sourcecode:: js + + { + "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}, + } + + :>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. + + +Builds +~~~~~~ + +Builds are created by Read the Docs whenever a ``Project`` has its documentation built. +Frequently this happens automatically via a web hook but can be triggered manually. + +Builds can be viewed in the build screen for a project. +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 detail +++++++++++++++ + +.. http:get:: /api/v2/build/{id}/ + + Retrieve details of a single build. + + .. sourcecode:: js + + { + "id": 7367364, + "date": "2018-06-19T15:15:59.135894", + "length": 59, + "type": "html", + "state": "finished", + "success": true, + "error": "", + "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30", + "docs_url": "http://pip.pypa.io/en/latest/", + "project": 13, + "project_slug": "pip", + "version": 3681, + "version_slug": "latest", + "commands": [ + { + "description": "", + "start_time": "2018-06-19T20:16:00.951959", + "exit_code": 0, + "build": 7367364, + "command": "git remote set-url origin git://github.com/pypa/pip.git", + "run_time": 0, + "output": "", + "id": 42852216, + "end_time": "2018-06-19T20:16:00.969170" + }, + ... + ], + ... + } + + + :>json integer id: The ID of the build + :>json string date: The ISO-8601 datetime of the build. + :>json integer length: The length of the build in seconds. + :>json string type: The type of the build (one of "html", "pdf", "epub") + :>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 docs_url: The canonical URL of the build docs + :>json integer project: The ID of the project being built + :>json string project_slug: The slug for the project being built + :>json integer version: The ID of the version of the project being built + :>json string version_slug: The slug for the version of the project being built + :>json array commands: Array of commands for the build with details including output. + + Some fields primarily used for UI elements in Read the Docs are omitted. + +Undocumented resources and endpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are some undocumented endpoints in the API. +These should not be used and could change at any time. +These include: + +* Endpoints for returning footer and version data to be injected into docs. + (``/api/v2/footer_html``) +* Endpoints used for advertising (``/api/v2/sustainability/``) +* Any other endpoints not detailed above. diff --git a/docs/builds.rst b/docs/builds.rst index 3adc1e2774e..3cdf2123651 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -108,7 +108,7 @@ Writing your own builder The documentation build system in RTD is made pluggable, so that you can build out your own backend. If you have a documentation format that isn't currently supported, you can add support by contributing a backend. -The :doc:`api/doc_builder` API explains the higher level parts of the API that you need to implement. A basic run goes something like this:: +The builders in :doc:`/developer-interface/doc_builder` detail the higher level parts of the API that you need to implement. A basic run goes something like this:: backend = get_backend(project.documentation_type) if force: diff --git a/docs/api/builds.rst b/docs/developer-interface/builds.rst similarity index 100% rename from docs/api/builds.rst rename to docs/developer-interface/builds.rst diff --git a/docs/api/core.rst b/docs/developer-interface/core.rst similarity index 100% rename from docs/api/core.rst rename to docs/developer-interface/core.rst diff --git a/docs/api/doc_builder.rst b/docs/developer-interface/doc_builder.rst similarity index 100% rename from docs/api/doc_builder.rst rename to docs/developer-interface/doc_builder.rst diff --git a/docs/developer-interface/index.rst b/docs/developer-interface/index.rst new file mode 100644 index 00000000000..7223d49ffa4 --- /dev/null +++ b/docs/developer-interface/index.rst @@ -0,0 +1,14 @@ +Developer Interface +=================== + +This part of the documentation covers +the classes, functions, and interfaces of Read the Docs. +It is autogenerated from the source code. + +.. toctree:: + + builds + doc_builder + core + projects + vcs_support diff --git a/docs/api/projects.rst b/docs/developer-interface/projects.rst similarity index 100% rename from docs/api/projects.rst rename to docs/developer-interface/projects.rst diff --git a/docs/api/vcs_support.rst b/docs/developer-interface/vcs_support.rst similarity index 100% rename from docs/api/vcs_support.rst rename to docs/developer-interface/vcs_support.rst diff --git a/docs/index.rst b/docs/index.rst index e421ef3da85..629057dca71 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,7 +44,7 @@ Information about development is also available: faq yaml-config guides/index - api + api/index embed .. _about-docs: @@ -105,7 +105,7 @@ Information about development is also available: i18n issue-labels security - api/index + developer-interface/index .. _business-docs: From 345b48a224619b92e07428f4c5597dce45f10fe8 Mon Sep 17 00:00:00 2001 From: David Fischer Date: Wed, 20 Jun 2018 10:01:29 -0700 Subject: [PATCH 2/5] Remove developer interface (class/function) docs --- docs/developer-interface/builds.rst | 23 --------- docs/developer-interface/core.rst | 65 ------------------------ docs/developer-interface/doc_builder.rst | 21 -------- docs/developer-interface/index.rst | 14 ----- docs/developer-interface/projects.rst | 46 ----------------- docs/developer-interface/vcs_support.rst | 9 ---- docs/index.rst | 1 - 7 files changed, 179 deletions(-) delete mode 100644 docs/developer-interface/builds.rst delete mode 100644 docs/developer-interface/core.rst delete mode 100644 docs/developer-interface/doc_builder.rst delete mode 100644 docs/developer-interface/index.rst delete mode 100644 docs/developer-interface/projects.rst delete mode 100644 docs/developer-interface/vcs_support.rst diff --git a/docs/developer-interface/builds.rst b/docs/developer-interface/builds.rst deleted file mode 100644 index c8476c398ea..00000000000 --- a/docs/developer-interface/builds.rst +++ /dev/null @@ -1,23 +0,0 @@ -:mod:`readthedocs.builds` -========================= - -:mod:`readthedocs.builds.admin` -------------------------------- -.. automodule:: readthedocs.builds.admin - :members: - -:mod:`readthedocs.builds.models` --------------------------------- -.. automodule:: readthedocs.builds.models - :members: - -:mod:`readthedocs.builds.urls` ------------------------------- -.. automodule:: readthedocs.builds.urls - :members: - -:mod:`readthedocs.builds.views` -------------------------------- -.. automodule:: readthedocs.builds.views - :members: - diff --git a/docs/developer-interface/core.rst b/docs/developer-interface/core.rst deleted file mode 100644 index b0b99966212..00000000000 --- a/docs/developer-interface/core.rst +++ /dev/null @@ -1,65 +0,0 @@ -:mod:`readthedocs.core` -======================= - -:mod:`readthedocs.core.admin` ------------------------------ -.. automodule:: readthedocs.core.admin - :members: - -:mod:`readthedocs.core.forms` ------------------------------ -.. automodule:: readthedocs.core.forms - :members: - -:mod:`readthedocs.core.middleware` ----------------------------------- -.. automodule:: readthedocs.core.middleware - :members: - -:mod:`readthedocs.core.models` ------------------------------- -.. automodule:: readthedocs.core.models - :members: - -:mod:`readthedocs.core.views` ------------------------------ -.. automodule:: readthedocs.core.views - :members: - - -:mod:`readthedocs.core.management.commands` -------------------------------------------- -This is where custom ``manage.py`` commands are defined. - -.. automodule:: readthedocs.core.management.commands.archive - :members: - -.. automodule:: readthedocs.core.management.commands.clean_builds - :members: - -.. automodule:: readthedocs.core.management.commands.import_github_language - :members: - -.. automodule:: readthedocs.core.management.commands.import_github - :members: - -.. automodule:: readthedocs.core.management.commands.pull - :members: - -.. automodule:: readthedocs.core.management.commands.reindex_elasticsearch - :members: - -.. automodule:: readthedocs.core.management.commands.set_metadata - :members: - -.. automodule:: readthedocs.core.management.commands.symlink - :members: - -.. automodule:: readthedocs.core.management.commands.update_api - :members: - -.. automodule:: readthedocs.core.management.commands.update_repos - :members: - -.. automodule:: readthedocs.core.management.commands.update_versions - :members: diff --git a/docs/developer-interface/doc_builder.rst b/docs/developer-interface/doc_builder.rst deleted file mode 100644 index 10580d9c91d..00000000000 --- a/docs/developer-interface/doc_builder.rst +++ /dev/null @@ -1,21 +0,0 @@ -:mod:`readthedocs.doc_builder` -============================== - -:mod:`readthedocs.doc_builder.base` ------------------------------------ -.. automodule:: readthedocs.doc_builder.base - :members: - -:mod:`readthedocs.doc_builder.environments` -------------------------------------------- -.. automodule:: readthedocs.doc_builder.environments - :members: - -:mod:`readthedocs.doc_builder.backends` ---------------------------------------- - - -:mod:`readthedocs.doc_builder.backends.sphinx` ----------------------------------------------- -.. automodule:: readthedocs.doc_builder.backends.sphinx - :members: diff --git a/docs/developer-interface/index.rst b/docs/developer-interface/index.rst deleted file mode 100644 index 7223d49ffa4..00000000000 --- a/docs/developer-interface/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -Developer Interface -=================== - -This part of the documentation covers -the classes, functions, and interfaces of Read the Docs. -It is autogenerated from the source code. - -.. toctree:: - - builds - doc_builder - core - projects - vcs_support diff --git a/docs/developer-interface/projects.rst b/docs/developer-interface/projects.rst deleted file mode 100644 index d17907f916d..00000000000 --- a/docs/developer-interface/projects.rst +++ /dev/null @@ -1,46 +0,0 @@ -:mod:`readthedocs.projects` -=========================== - -:mod:`readthedocs.projects.admin` ---------------------------------- -.. automodule:: readthedocs.projects.admin - :members: - -:mod:`readthedocs.projects.constants` -------------------------------------- -.. automodule:: readthedocs.projects.constants - :members: - -:mod:`readthedocs.projects.forms` ---------------------------------- -.. automodule:: readthedocs.projects.forms - :members: - -:mod:`readthedocs.projects.models` ----------------------------------- -.. automodule:: readthedocs.projects.models - :members: - -:mod:`readthedocs.projects.tasks` ---------------------------------- -.. automodule:: readthedocs.projects.tasks - :members: - -:mod:`readthedocs.projects.utils` ---------------------------------- -.. automodule:: readthedocs.projects.utils - :members: - -:mod:`readthedocs.projects.views` ---------------------------------- - -:mod:`readthedocs.projects.views.public` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: readthedocs.projects.views.public - :members: - -:mod:`readthedocs.projects.views.private` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: readthedocs.projects.views.private - :members: - diff --git a/docs/developer-interface/vcs_support.rst b/docs/developer-interface/vcs_support.rst deleted file mode 100644 index d801503a0e9..00000000000 --- a/docs/developer-interface/vcs_support.rst +++ /dev/null @@ -1,9 +0,0 @@ -:mod:`readthedocs.vcs_support` -============================== - -:mod:`readthedocs.vcs_support.base` ------------------------------------ - -.. automodule:: readthedocs.vcs_support.base - :members: - diff --git a/docs/index.rst b/docs/index.rst index 629057dca71..1aac582e0b2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -105,7 +105,6 @@ Information about development is also available: i18n issue-labels security - developer-interface/index .. _business-docs: From 48aec8c0b7b40d9704083307ee420f800ab6136e Mon Sep 17 00:00:00 2001 From: David Fischer Date: Wed, 20 Jun 2018 10:03:20 -0700 Subject: [PATCH 3/5] Fix a typo --- docs/api/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/index.rst b/docs/api/index.rst index cd0c4ad7b4c..6e263bdefeb 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -16,7 +16,7 @@ from Read the Docs. 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 we Read the Docs' team can contact you in the event of issues. + That way the Read the Docs' team can contact you in the event of issues. .. toctree:: From eb308da69d2b81321792d481265602a33752cb08 Mon Sep 17 00:00:00 2001 From: David Fischer Date: Wed, 20 Jun 2018 10:36:00 -0700 Subject: [PATCH 4/5] Remove search API --- docs/api/v2.rst | 56 +++++++++++++------------------------------------ 1 file changed, 14 insertions(+), 42 deletions(-) diff --git a/docs/api/v2.rst b/docs/api/v2.rst index 65e94f01425..e9d103bbb2b 100644 --- a/docs/api/v2.rst +++ b/docs/api/v2.rst @@ -10,6 +10,7 @@ and HTTP response status codes are to designate success and failure. A newer API v3 is in early development stages. Some improvements coming in v3 are: + * Search API * Write access * Simpler URLs which use slugs instead of numeric IDs * Improved error reporting @@ -43,44 +44,6 @@ You can always view your Read the Docs projects in your `project dashboard`_. .. _Docs project: https://readthedocs.org/projects/docs/ .. _project dashboard: https://readthedocs.org/dashboard/ -Project search -++++++++++++++ - -.. tip:: - - This API is in need of simplifying for end users. - Largely this endpoint should be used only to get the Project ID - which is used in other API calls. - -.. http:get:: /api/v2/search/project/?q={query} - - Search for projects by name or description. - Results are returned in order of the best match. - - .. sourcecode:: js - - { - "results": { - "hits": { - "hits": [ - { - "fields": { - // Returned fields - }, - "_id": "13" // Project ID - }, - ], - }, - "facets": { - // Facet Data - }, - "took": 15, - "timed_out": false, - } - } - - :>json array results: An array of matching results - Project list ++++++++++++ @@ -97,7 +60,6 @@ Project list "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. @@ -106,7 +68,7 @@ Project list Project details +++++++++++++++ -.. http:get:: /api/v2/project/{id}/ +.. http:get:: /api/v2/project/(int:id)/ Retrieve details of a single project. @@ -143,10 +105,13 @@ Project details :>json string canonical_url: The canonical URL of the default docs :>json array users: Array of ``User`` IDs who are maintainers of the project. + :statuscode 200: no error + :statuscode 404: There is no ``Project`` with this ID + Project versions ++++++++++++++++ -.. http:get:: /api/v2/project/{id}/active_versions/ +.. http:get:: /api/v2/project/(int:id)/active_versions/ Retrieve a list of active versions (eg. "latest", "stable", "v1.x") for a single project. @@ -220,7 +185,7 @@ Version list Version detail ++++++++++++++ -.. http:get:: /api/v2/version/{id}/ +.. http:get:: /api/v2/version/(int:id)/ Retrieve details of a single version. @@ -252,6 +217,9 @@ Version detail :>json array downloads: URLs to downloads of this version's documentation :>json object project: Details of the ``Project`` for this version. + :statuscode 200: no error + :statuscode 404: There is no ``Version`` with this ID + Builds ~~~~~~ @@ -323,6 +291,9 @@ Build detail :>json string version_slug: The slug for the version of the project being built :>json array commands: Array of commands for the build with details including output. + :statuscode 200: no error + :statuscode 404: There is no ``Build`` with this ID + Some fields primarily used for UI elements in Read the Docs are omitted. Undocumented resources and endpoints @@ -332,6 +303,7 @@ There are some undocumented endpoints in the API. These should not be used and could change at any time. These include: +* The search API (``/api/v2/search/``) * Endpoints for returning footer and version data to be injected into docs. (``/api/v2/footer_html``) * Endpoints used for advertising (``/api/v2/sustainability/``) From cb1bb70366292d707a981020e56d20ace99b4580 Mon Sep 17 00:00:00 2001 From: David Fischer Date: Wed, 20 Jun 2018 11:13:27 -0700 Subject: [PATCH 5/5] Note that build ID is an int --- docs/api/v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/v2.rst b/docs/api/v2.rst index e9d103bbb2b..05342f21e38 100644 --- a/docs/api/v2.rst +++ b/docs/api/v2.rst @@ -238,7 +238,7 @@ For example, here is `Pip's build screen`_. Build detail ++++++++++++++ -.. http:get:: /api/v2/build/{id}/ +.. http:get:: /api/v2/build/(int:id)/ Retrieve details of a single build.