Skip to content

Commit

Permalink
API: simplify and standardize data usage (#281)
Browse files Browse the repository at this point in the history 
Implements the changes in the API made in
readthedocs/readthedocs.org#11205. We need to
merge that PR and deploy addons together with the changes in this PR.

In this PR there are mainly no changes in the logic. The most important
thing to mention here is that we are standardizing the usage of the API
response and pinning to `v1` now (we were using `v0-alpha`). This means:

- we will be exposing the `v1` to users via the js custom event (see
#64)
- we are using standard/shared APIv3 serializers for resources for this
`/addons/` endpoint
- any breaking change we have to do in the future it will increase the
API response version


I'm not sure there are too much to review here, but I'd appreciate at
least a quick look at these changes. I'm happy to answer some questions
you may have here or on the underlying PR about the API response
changes.


### Related:
* Closes #132 
* Unblocks #265
* Unblocks theme integration (our theme and CPython's one)
* Requires readthedocs/readthedocs.org#11205

---------

Co-authored-by: Anthony <[email protected]>
  • Loading branch information
@humitos @agjohnson
humitos and agjohnson authored Apr 11, 2024
1 parent 2de7016 commit cb57a67
Show file tree
Hide file tree
Showing 12 changed files with 373 additions and 191 deletions.
26 changes: 13 additions & 13 deletions dist/readthedocs-addons.js
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion dist/readthedocs-addons.js.map
View file

Large diffs are not rendered by default.

98 changes: 60 additions & 38 deletions public/_/readthedocs-addons.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
{
"api_version": "0",
"comment": "THIS RESPONSE IS IN ALPHA FOR TEST PURPOSES ONLY AND IT'S GOING TO CHANGE COMPLETELY -- DO NOT USE IT!",
"api_version": "1",
"projects": {
"current": {
"slug": "example",
Expand All @@ -14,18 +13,72 @@
"programming_language": {
"code": "words"
},
"versioning_scheme": "multiple_versions_with_translations"
}
"versioning_scheme": "multiple_versions_with_translations",
"urls": {
"documentation": "http://localhost:8000/en/v1.0/",
"home": "https://devthedocs.org/projects/example/",
"builds": "https://devthedocs.org/projects/example/builds/",
"downloads": "https://devthedocs.org/projects/example/downloads/"
}
},
"translations": [
{
"slug": "example-es",
"language": {
"code": "es"
},
"urls": {
"documentation": "http://localhost:8000/es/v1.0/"
}
}
]
},
"versions": {
"active": [
{
"slug": "stable",
"urls": {
"documentation": "http://localhost:8000/en/stable/"
}
},
{
"slug": "latest",
"urls": {
"documentation": "http://localhost:8000/en/latest/"
}
},
{
"slug": "v1.0",
"urls": {
"documentation": "http://localhost:8000/en/v1.0/"
}
},
{
"slug": "v1.4",
"urls": {
"documentation": "http://localhost:8000/en/v1.4/"
}
},
{
"slug": "v2.0",
"urls": {
"documentation": "http://localhost:8000/en/v2.0/"
}
}
],
"current": {
"slug": "v1.0",
"type": "external"
"type": "external",
"downloads": {
"pdf": "https://localhost:8000/_/downloads/en/v1.0/pdf/"
}
}
},
"builds": {
"current": {
"id": 2801
"urls": {
"build": "https://localhost:8000/projects/example/builds/1234/"
}
}
},
"domains": {
Expand Down Expand Up @@ -69,38 +122,10 @@
},
"flyout": {
"enabled": true,
"translations": [
{
"slug": "es",
"url": "http://localhost:8000/es/v1.0/"
}
],
"versions": [
{
"slug": "stable",
"url": "http://localhost:8000/en/stable/"
},
{
"slug": "latest",
"url": "http://localhost:8000/en/latest/"
},
{
"slug": "v1.0",
"url": "http://localhost:8000/en/v1.0/"
},
{
"slug": "v1.4",
"url": "http://localhost:8000/en/v1.4/"
},
{
"slug": "v2.0",
"url": "http://localhost:8000/en/v2.0/"
}
],
"downloads": [
{
"name": "PDF",
"url": "/_/downloads/en/latest/"
"url": "/_/downloads/en/latest/pdf/"
}
],
"vcs": {
Expand All @@ -115,9 +140,6 @@
},
"search": {
"enabled": true,
"project": "example",
"version": "latest",
"api_endpoint": "/_/api/v3/search/",
"filters": [
["Search only in this project", "project:example/latest"],
["Search subprojects", "subprojects:example/latest"]
Expand Down
112 changes: 86 additions & 26 deletions src/data-validation.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ const addons_ethicalads = {
const addons_flyout = {
$id: "http://v1.schemas.readthedocs.org/addons.flyout.json",
type: "object",
required: ["addons", "domains", "projects", "versions"],
required: ["addons", "projects", "versions"],
properties: {
addons: {
type: "object",
Expand All @@ -135,17 +135,11 @@ const addons_flyout = {
type: "object",
required: [
"enabled",
"downloads",
"translations",
"versions",
// TODO: make it required when we support VCS links
// "vcs",
],
properties: {
enabled: { type: "boolean" },
downloads: { type: "array" },
translations: { type: "array" },
versions: { type: "array" },
vcs: {
type: "object",
properties: {
Expand All @@ -156,22 +150,24 @@ const addons_flyout = {
},
},
},
domains: {
type: "object",
required: ["dashboard"],
properties: {
dashboard: { type: "string" },
},
},
projects: {
type: "object",
required: ["current"],
required: ["current", "translations"],
properties: {
current: {
type: "object",
required: ["slug", "versioning_scheme"],
required: ["slug", "urls", "versioning_scheme"],
properties: {
slug: { type: "string" },
urls: {
type: "object",
required: ["home", "builds", "downloads"],
properties: {
home: { type: "string" },
builds: { type: "string" },
downloads: { type: "string" },
},
},
versioning_scheme: {
enum: [
"multiple_versions_with_translations",
Expand All @@ -181,17 +177,61 @@ const addons_flyout = {
},
},
},
translations: {
type: "array",
// TODO: validate each item of the array has the following structure
//
// items: { type: "object" },
// required: ["slug", "urls", "language"],
// properties: {
// slug: { type: "string" },
// language: {
// type: "object",
// required: ["code"],
// properties: {
// code: { type: "string" },
// },
// },
// urls: {
// type: "object",
// required: ["documentation"],
// properties: {
// documentation: { type: "string" },
// },
// },
// },
},
},
},
versions: {
type: "object",
required: ["current"],
required: ["current", "active"],
properties: {
active: {
type: "array",
// TODO: validate each item of the array has the following structure
//
// items: { type: "object" },
// required: ["slug", "urls"],
// properties: {
// slug: { type: "string" },
// urls: {
// type: "object",
// required: ["documentation"],
// properties: {
// documentation: { type: "string" },
// },
// },
// },
},
current: {
type: "object",
required: ["slug"],
required: ["slug", "downloads"],
properties: {
slug: { type: "string" },
downloads: {
type: "object",
},
},
},
},
Expand Down Expand Up @@ -257,28 +297,28 @@ const addons_notifications = {
type: "object",
properties: {
enabled: { type: "boolean" },
versions: { type: "array" },
},
},
},
},
builds: {
type: "object",
required: ["current"],
properties: {
current: {
type: "object",
required: ["urls"],
properties: {
id: { type: "integer" },
urls: {
type: "object",
properties: {
build: { type: "string" },
},
},
},
},
},
},
domains: {
type: "object",
properties: {
dashboard: { type: "string" },
},
},
projects: {
type: "object",
properties: {
Expand Down Expand Up @@ -314,12 +354,32 @@ const addons_notifications = {
},
versions: {
type: "object",
required: ["current", "active"],
properties: {
active: {
type: "array",
// TODO: validate each item of the array has the following structure
//
// items: { type: "object" },
// required: ["slug", "urls", "aliases"],
// properties: {
// slug: { type: "string" },
// urls: {
// type: "object",
// required: ["documentation"],
// properties: {
// documentation: { type: "string" },
// },
// },
// },
},
current: {
type: "object",
required: ["slug", "type", "aliases"],
properties: {
slug: { type: "string" },
type: { enum: ["branch", "tag", "external"] },
aliases: { type: "array" },
},
},
},
Expand Down
Loading

0 comments on commit cb57a67

Please sign in to comment.