APIv3 Design Document¶
This document describes the design, some decisions already made and built (current Version 1 of APIv3) and an implementation plan for next Versions of APIv3.
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 (access most of resources by
slug
) - Useful to perform read and write operations
- Authentication/Authorization
- Authentication based on scoped-tokens
- Handle Authorization nicely using an abstraction layer
- Cover most useful cases:
- Integration on CI (check build status, trigger new build, etc)
- Usage from public Sphinx/MkDocs extensions
- Allow creation of flyout menu client-side
- Simplify migration from other services (import projects, create multiple redirects, etc)
Non-Goals¶
- Filter by arbitrary and non-useful fields
- "Builds with
exit_code=1
" - "Builds containing
ERROR
on their output" - "Projects created after X datetime"
- "Versions with tag
python
"
- "Builds with
- 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
- Not designed for slugs
- Useful APIs not exposed (only for internal usage currently)
- Error reporting is a mess
- Relationships between API resources is not obvious
- Footer API endpoint returns HTML
Implementation stages¶
Version 1¶
The first implementation of APIv3 will cover the following aspects:
- Authentication
- 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
- all endpoints require authentication via
- Read and Write
- edit attributes from Version (only
active
andprivacy_level
) - trigger Build for a specific Version
- edit attributes from Version (only
- 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
- Projects are accessed by
- Proper status codes to report errors
- Browse-able endpoints
- browse is allowed hitting
/api/v3/projects/
as starting point - ability to navigate clicking on other resources under
_links
attribute
- browse is allowed hitting
- Rate limited
Version 2¶
注釈
This is currently implemented and live.
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.
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.
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
andEmailHook
) - Create/Delete a Project as subproject of another Project
- Documentation
Version 3¶
Third iteration will implement granular permissions. Keeping in mind how Sphinx extension will use it:
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
To fulfill these requirements, this iteration will include:
- Scope-based authorization token
Version 4¶
- Specific endpoint for our flyout menu (returning JSON instead of HTML)
Out of roadmap¶
These are some features that we may want to build at some point. Although, they are currently out of our near roadmap because they don't affect too many users, or are for internal usage only.
- CRUD for Domain
- Add User as maintainer
- Give access to a documentation page (
objects.inv
,/design/core.html
) - Internal Build process
Nice to have¶
Request-ID
header- JSON minified by default (maybe with
?pretty=true
) - JSON schema and validation with docs