Skip to content

Commit cb57a67

Browse files
humitosagjohnson
humitos
and
agjohnson
authored
API: simplify and standardize data usage (#281)
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]>
1 parent 2de7016 commit cb57a67

12 files changed

+373
-191
lines changed

‎dist/readthedocs-addons.js

+13-13
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/readthedocs-addons.js.map

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎public/_/readthedocs-addons.json

+60-38
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
{
2-
"api_version": "0",
3-
"comment": "THIS RESPONSE IS IN ALPHA FOR TEST PURPOSES ONLY AND IT'S GOING TO CHANGE COMPLETELY -- DO NOT USE IT!",
2+
"api_version": "1",
43
"projects": {
54
"current": {
65
"slug": "example",
@@ -14,18 +13,72 @@
1413
"programming_language": {
1514
"code": "words"
1615
},
17-
"versioning_scheme": "multiple_versions_with_translations"
18-
}
16+
"versioning_scheme": "multiple_versions_with_translations",
17+
"urls": {
18+
"documentation": "http://localhost:8000/en/v1.0/",
19+
"home": "https://devthedocs.org/projects/example/",
20+
"builds": "https://devthedocs.org/projects/example/builds/",
21+
"downloads": "https://devthedocs.org/projects/example/downloads/"
22+
}
23+
},
24+
"translations": [
25+
{
26+
"slug": "example-es",
27+
"language": {
28+
"code": "es"
29+
},
30+
"urls": {
31+
"documentation": "http://localhost:8000/es/v1.0/"
32+
}
33+
}
34+
]
1935
},
2036
"versions": {
37+
"active": [
38+
{
39+
"slug": "stable",
40+
"urls": {
41+
"documentation": "http://localhost:8000/en/stable/"
42+
}
43+
},
44+
{
45+
"slug": "latest",
46+
"urls": {
47+
"documentation": "http://localhost:8000/en/latest/"
48+
}
49+
},
50+
{
51+
"slug": "v1.0",
52+
"urls": {
53+
"documentation": "http://localhost:8000/en/v1.0/"
54+
}
55+
},
56+
{
57+
"slug": "v1.4",
58+
"urls": {
59+
"documentation": "http://localhost:8000/en/v1.4/"
60+
}
61+
},
62+
{
63+
"slug": "v2.0",
64+
"urls": {
65+
"documentation": "http://localhost:8000/en/v2.0/"
66+
}
67+
}
68+
],
2169
"current": {
2270
"slug": "v1.0",
23-
"type": "external"
71+
"type": "external",
72+
"downloads": {
73+
"pdf": "https://localhost:8000/_/downloads/en/v1.0/pdf/"
74+
}
2475
}
2576
},
2677
"builds": {
2778
"current": {
28-
"id": 2801
79+
"urls": {
80+
"build": "https://localhost:8000/projects/example/builds/1234/"
81+
}
2982
}
3083
},
3184
"domains": {
@@ -69,38 +122,10 @@
69122
},
70123
"flyout": {
71124
"enabled": true,
72-
"translations": [
73-
{
74-
"slug": "es",
75-
"url": "http://localhost:8000/es/v1.0/"
76-
}
77-
],
78-
"versions": [
79-
{
80-
"slug": "stable",
81-
"url": "http://localhost:8000/en/stable/"
82-
},
83-
{
84-
"slug": "latest",
85-
"url": "http://localhost:8000/en/latest/"
86-
},
87-
{
88-
"slug": "v1.0",
89-
"url": "http://localhost:8000/en/v1.0/"
90-
},
91-
{
92-
"slug": "v1.4",
93-
"url": "http://localhost:8000/en/v1.4/"
94-
},
95-
{
96-
"slug": "v2.0",
97-
"url": "http://localhost:8000/en/v2.0/"
98-
}
99-
],
100125
"downloads": [
101126
{
102127
"name": "PDF",
103-
"url": "/_/downloads/en/latest/"
128+
"url": "/_/downloads/en/latest/pdf/"
104129
}
105130
],
106131
"vcs": {
@@ -115,9 +140,6 @@
115140
},
116141
"search": {
117142
"enabled": true,
118-
"project": "example",
119-
"version": "latest",
120-
"api_endpoint": "/_/api/v3/search/",
121143
"filters": [
122144
["Search only in this project", "project:example/latest"],
123145
["Search subprojects", "subprojects:example/latest"]

‎src/data-validation.js

+86-26
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ const addons_ethicalads = {
125125
const addons_flyout = {
126126
$id: "http://v1.schemas.readthedocs.org/addons.flyout.json",
127127
type: "object",
128-
required: ["addons", "domains", "projects", "versions"],
128+
required: ["addons", "projects", "versions"],
129129
properties: {
130130
addons: {
131131
type: "object",
@@ -135,17 +135,11 @@ const addons_flyout = {
135135
type: "object",
136136
required: [
137137
"enabled",
138-
"downloads",
139-
"translations",
140-
"versions",
141138
// TODO: make it required when we support VCS links
142139
// "vcs",
143140
],
144141
properties: {
145142
enabled: { type: "boolean" },
146-
downloads: { type: "array" },
147-
translations: { type: "array" },
148-
versions: { type: "array" },
149143
vcs: {
150144
type: "object",
151145
properties: {
@@ -156,22 +150,24 @@ const addons_flyout = {
156150
},
157151
},
158152
},
159-
domains: {
160-
type: "object",
161-
required: ["dashboard"],
162-
properties: {
163-
dashboard: { type: "string" },
164-
},
165-
},
166153
projects: {
167154
type: "object",
168-
required: ["current"],
155+
required: ["current", "translations"],
169156
properties: {
170157
current: {
171158
type: "object",
172-
required: ["slug", "versioning_scheme"],
159+
required: ["slug", "urls", "versioning_scheme"],
173160
properties: {
174161
slug: { type: "string" },
162+
urls: {
163+
type: "object",
164+
required: ["home", "builds", "downloads"],
165+
properties: {
166+
home: { type: "string" },
167+
builds: { type: "string" },
168+
downloads: { type: "string" },
169+
},
170+
},
175171
versioning_scheme: {
176172
enum: [
177173
"multiple_versions_with_translations",
@@ -181,17 +177,61 @@ const addons_flyout = {
181177
},
182178
},
183179
},
180+
translations: {
181+
type: "array",
182+
// TODO: validate each item of the array has the following structure
183+
//
184+
// items: { type: "object" },
185+
// required: ["slug", "urls", "language"],
186+
// properties: {
187+
// slug: { type: "string" },
188+
// language: {
189+
// type: "object",
190+
// required: ["code"],
191+
// properties: {
192+
// code: { type: "string" },
193+
// },
194+
// },
195+
// urls: {
196+
// type: "object",
197+
// required: ["documentation"],
198+
// properties: {
199+
// documentation: { type: "string" },
200+
// },
201+
// },
202+
// },
203+
},
184204
},
185205
},
186206
versions: {
187207
type: "object",
188-
required: ["current"],
208+
required: ["current", "active"],
189209
properties: {
210+
active: {
211+
type: "array",
212+
// TODO: validate each item of the array has the following structure
213+
//
214+
// items: { type: "object" },
215+
// required: ["slug", "urls"],
216+
// properties: {
217+
// slug: { type: "string" },
218+
// urls: {
219+
// type: "object",
220+
// required: ["documentation"],
221+
// properties: {
222+
// documentation: { type: "string" },
223+
// },
224+
// },
225+
// },
226+
},
190227
current: {
191228
type: "object",
192-
required: ["slug"],
229+
required: ["slug", "downloads"],
193230
properties: {
194231
slug: { type: "string" },
232+
downloads: {
233+
type: "object",
234+
},
195235
},
196236
},
197237
},
@@ -257,28 +297,28 @@ const addons_notifications = {
257297
type: "object",
258298
properties: {
259299
enabled: { type: "boolean" },
260-
versions: { type: "array" },
261300
},
262301
},
263302
},
264303
},
265304
builds: {
266305
type: "object",
306+
required: ["current"],
267307
properties: {
268308
current: {
269309
type: "object",
310+
required: ["urls"],
270311
properties: {
271-
id: { type: "integer" },
312+
urls: {
313+
type: "object",
314+
properties: {
315+
build: { type: "string" },
316+
},
317+
},
272318
},
273319
},
274320
},
275321
},
276-
domains: {
277-
type: "object",
278-
properties: {
279-
dashboard: { type: "string" },
280-
},
281-
},
282322
projects: {
283323
type: "object",
284324
properties: {
@@ -314,12 +354,32 @@ const addons_notifications = {
314354
},
315355
versions: {
316356
type: "object",
357+
required: ["current", "active"],
317358
properties: {
359+
active: {
360+
type: "array",
361+
// TODO: validate each item of the array has the following structure
362+
//
363+
// items: { type: "object" },
364+
// required: ["slug", "urls", "aliases"],
365+
// properties: {
366+
// slug: { type: "string" },
367+
// urls: {
368+
// type: "object",
369+
// required: ["documentation"],
370+
// properties: {
371+
// documentation: { type: "string" },
372+
// },
373+
// },
374+
// },
375+
},
318376
current: {
319377
type: "object",
378+
required: ["slug", "type", "aliases"],
320379
properties: {
321380
slug: { type: "string" },
322381
type: { enum: ["branch", "tag", "external"] },
382+
aliases: { type: "array" },
323383
},
324384
},
325385
},

0 commit comments

Comments
 (0)