Re-work around design document for APIv3 #5845
Conversation
This commit, * describes main Goals/Non-Goals * includes implementation plan based on stages * updates the document mentioning what's already implemented (Version 1) * proposes a plan for iteration 2, 3 and 4 * mentions open questions for further discussion * includes potential feature out of the current roadmap
docs/development/design/apiv3.rst
Outdated
| @@ -1,15 +1,34 @@ | |||
| Design of APIv3 | |||
| =============== | |||
| APIv3 | |||
There was a problem hiding this comment.
I think we should include design in the title still, so it's easier to find in search, etc.
docs/development/design/apiv3.rst
Outdated
| ===== | ||
|
|
||
| This document describes the design, | ||
| some decisions already made and an implementation plan for APIv3 in stages. |
There was a problem hiding this comment.
This sentence needs something connecting the 2 halves.
There was a problem hiding this comment.
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 :)
docs/development/design/apiv3.rst
Outdated
|
|
||
| * Easy to use for our users | ||
| * Useful to perform read and write operations | ||
| * Cover most useful cases |
There was a problem hiding this comment.
This needs to be clearer. We should define these.
There was a problem hiding this comment.
I expand the list. Looks better now and more concise.
| Non-Goals | ||
| --------- | ||
|
|
||
| * Filter by arbitrary and non-useful fields |
There was a problem hiding this comment.
Again, this isn't clear, we need to define this more.
| * CRUD for Domain | ||
| * Add User as maintainer | ||
| * Give access to a documentation page (``objects.inv``, ``/design/core.html``) | ||
| * Internal Build process |
There was a problem hiding this comment.
We should mention why all of these are out of the roadmap.
There was a problem hiding this comment.
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.
docs/development/design/apiv3.rst
Outdated
| * "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? |
There was a problem hiding this comment.
Definitely not on both of these. We can remove them.
docs/development/design/apiv3.rst
Outdated
| * "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? | ||
| * Should we make our search endpoint at ``/api/v2/search`` publicly on APIv3? |
There was a problem hiding this comment.
I don't believe this exists. Are you talking about docsearch?
We are not building this endpoints
|
@ericholscher I worked on the feedback you gave me. It looks better to me now. Let me know if there are more things to tackle. |
|
@ericholscher thanks you for the good feedback 😉 |
This commit,
mentions open questions for further discussion