Skip to content

Re-work around design document for APIv3 #5845

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 26, 2019
Merged

Re-work around design document for APIv3 #5845

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
48e2eda
Re-work around design document for APIv3
humitos Jun 25, 2019
a6e929a
Improve title
humitos Jun 26, 2019
cd8c163
Add table of contents
humitos Jun 26, 2019
02ce6ec
Remove open questions
humitos Jun 26, 2019
cb6c87a
Explain more Out of roadmap
humitos Jun 26, 2019
71d07cf
Expand introduction
humitos Jun 26, 2019
250ee1f
Better Goals and Non-Goals
humitos Jun 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
233 changes: 92 additions & 141 deletions docs/development/design/apiv3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,34 @@
Design of APIv3
===============
APIv3
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should include design in the title still, so it's easier to find in search, etc.

=====

This document describes the design,
some decisions already made and an implementation plan for APIv3 in stages.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence needs something connecting the 2 halves.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure to understand what you refers to here. I expanded a little more the sentence, but I don't think that is what you want though :)


APIv3 will be designed to be easy to use and useful to perform read and write operations as the main two goals.

It will be based on Resources as APIv2 but considering the ``Project`` resource as the main one,
from where most of the endpoint will be based on it.


Goals
-----

* Easy to use for our users
* Useful to perform read and write operations
* Cover most useful cases
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to be clearer. We should define these.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expand the list. Looks better now and more concise.



Non-Goals
---------

* Filter by arbitrary and non-useful fields
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, this isn't clear, we need to define this more.

* Cover *all the actions* available from the WebUI


Problems with APIv2
-------------------

There are several problem with our current APIv2 that we can list:

* No authentication
* It's read-only
Expand All @@ -20,185 +39,117 @@ Problems with APIv2
* Footer API endpoint returns HTML


Proposed improves
+++++++++++++++++


Use authentication
~~~~~~~~~~~~~~~~~~

* Pros:

* queries can be personalized depending on the user
* allows us to perform write actions

* Cons:

* harder to implement
* requires a lot of time for good testing and QA


Questions:

#. Do we want make auth a requirement?
#. Should we expose some endpoints as Read Only if not authenticated?
#. How we do communicate users about deprecation if they are Anonymous? Is it enough to add a note in the docs saying that "Auth is preferred for communication"?
#. How are we going to expose the ``Token`` required for Auth when building if auth is mandatory?


Read and Write
~~~~~~~~~~~~~~

* Pros:

* most of the actions can be performed by a script instead of by
accessing readthedocs.org with a browser

* Cons:

* we have to deal with authorization
* open the door to possibilities of security holes
Implementation stages
---------------------

Version 1
+++++++++

Questions:
The first implementation of APIv3 will cover the following aspects:

#. Do we want to allow the user to perform **all the write actions**
that are possible to do from the dashboard via the API?
.. note::

This is currently implemented and live. Although, it's only for internal testing.

Design it for slugs
~~~~~~~~~~~~~~~~~~~
* Authentication

* Pros:
* all endpoints require authentication via ``Authorization:`` request header
* detail endpoints are available for all authenticated users
* only Project's maintainers can access listing endpoints
* personalized listing

* knowing the slug of your project (which is presented to the user)
you can perform all the actions or retrieve all the data
* Read and Write

* Cons:
* edit attributes from Version (only ``active`` and ``privacy_level``)
* trigger Build for a specific Version

* it will be a mixture between most of the endpoint using ``slug``
and to retrieve details of a Build it will be an ``id``
* Accessible by slug

* Projects are accessed by ``slug``
* Versions are accessed by ``slug``
* ``/projects/`` endpoint is the main one and all of the other are nested under it
* Builds are accessed by ``id``, as exception to this rule
* access all (active/non-active) Versions of a Project by ``slug``
* get latest Build for a Project (and Version) by ``slug``
* filter by relevant fields

Expose internal endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~
* Proper status codes to report errors

There are some endpoints that we are using internally like
``/api/v2/search/``, ``/api/v2/footer/`` and
``/api/v2/sustainability/``.
* Browse-able endpoints

* browse is allowed hitting ``/api/v3/projects/`` as starting point
* ability to navigate clicking on other resources under ``_links`` attribute

* Pros:
* Rate limited

* allow to build custom footer
* allow to build custom search autocomplete widget

* Cons:
Version 2
+++++++++

* n/a
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.

Questions:
After Version 2 is deployed,
we will invite users that reach us as beta testers to receive more feedback
and continue improving it by supporting more use cases.

#. Do we want to add ``/api/v2/sustainability/`` to APIv3 or that
should be part of the new Ad Server that we are building?
This iteration will include:

* Minor changes to fields returned in the objects
* Import Project endpoint
* 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``)
* Documentation

Proper status codes for error reporting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Pros:

* user knows what it's happening and can take decisions about it

* Cons:

* n/a


Relationship between API resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Pros:

* browse-able API by accessing to the default resource (Project)
* knowing the project's slug you can perform all the actions related to it

* Cons:

* more data is returned with all the links to the endpoints


Make footer API returns JSON
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Pros:

* users can build their own version menu flyout
* cleaner than returning a HTML and injecting it

* Cons:

* we need to adapt our theme for this


Questions:

#. Do we want an specific endpoint for the footer?
#. The flyout could be built by querying 2 or 3 of the regular
endpoint. Would this add too much overhead to the page loading
time?


Use cases
---------

We want to cover
++++++++++++++++
Version 3
+++++++++

Third iteration will implement granular permissions.
Keeping in mind how Sphinx extension will use it:

* Return all **my** projects
* Access all the resources by knowing the project's slug
* Ability to filter by fields
* ``sphinx-version-warning`` needs to get *all active Versions of a Project*
* An extension that creates a landing page, will need *all the subprojects of a Project*

* all the active versions of specific project
To fulfill these requirements, this iteration will include:

* Data about builds
* Scope-based authorization token

* latest build for project
* latest build for a particular version of a project
* status of a particular build

* Perform write actions like
Version 4
+++++++++

* add a Domain,
* add User as mantainer,
* import a new Project under my username,
* set the language of the Project,
* trigger a Build,
* activate/deactivate a Version to be built,
* and all the actions you can perform from the Admin tab.
* Specific endpoint for our flyout menu (returning JSON instead of HTML)

* Retrieve all the information needed to create a custom version menu flyout

Out of roadmap
--------------

Considering some useful cases for the corporate site:
These are some features that we may want to build but they are not in the roadmap at this moment:

* Give access to a doc page (``objects.inv``, ``/design/core.html``)
* CRUD for Domain
* Add User as maintainer
* Give access to a documentation page (``objects.inv``, ``/design/core.html``)
* Internal Build process
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should mention why all of these are out of the roadmap.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put them out of the roadmap for now because, in case we build them, we need to decide in which Version they will be assigned. Also, they do not affect too many users or are only for internal usage only.

I'm updating the paragraph mentioning this.



We do NOT want to cover
+++++++++++++++++++++++
Open questions
--------------

* Random filtering over a whole and not useful Resource
There are some questions that we still have.
These will need more discussion before making a decision on where,
when and how to implement them.

* "All the ``stable`` versions"
* "Builds with ``exit_code`` equal to 257"
* Do we want to add ``/api/v2/sustainability/`` to APIv3?
Should be part of the new "Ad Server" that we are building?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely not on both of these. We can remove them.

* Should we make our search endpoint at ``/api/v2/search`` publicly on APIv3?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't believe this exists. Are you talking about docsearch?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, docsearch



Technical aspects that would be good to have
--------------------------------------------
Nice to have
------------

* Rate limit
* ``Request-ID`` header
* `JSON minified by default`_ (maybe with ``?pretty=true``)
* `JSON schema and validation`_ with docs_
Expand Down