API: hosting integrations endpoint versioning/structure #10216
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| { | ||
| "comment": "THIS RESPONSE IS IN ALPHA FOR TEST PURPOSES ONLY AND IT'S GOING TO CHANGE COMPLETELY -- DO NOT USE IT!", | ||
| "project": { | ||
| "created": "2019-04-29T10:00:00Z", | ||
| "default_branch": "master", | ||
| "default_version": "latest", | ||
| "id": 1, | ||
| "language": { | ||
| "code": "en", | ||
| "name": "English" | ||
| }, | ||
| "modified": "2019-04-29T12:00:00Z", | ||
| "name": "project", | ||
| "programming_language": { | ||
| "code": "words", | ||
| "name": "Only Words" | ||
| }, | ||
| "homepage": "http://project.com", | ||
| "repository": { | ||
| "type": "git", | ||
| "url": "https://github.com/readthedocs/project" | ||
| }, | ||
| "slug": "project", | ||
| "subproject_of": null, | ||
| "tags": [ | ||
| "project", | ||
| "tag", | ||
| "test" | ||
| ], | ||
| "translation_of": null, | ||
| "users": [ | ||
| { | ||
| "username": "testuser" | ||
| } | ||
| ] | ||
| }, | ||
| "version": { | ||
| "active": true, | ||
| "hidden": false, | ||
| "built": true, | ||
| "downloads": {}, | ||
| "id": 1, | ||
| "identifier": "a1b2c3", | ||
| "ref": null, | ||
| "slug": "latest", | ||
| "type": "tag", | ||
| "verbose_name": "latest" | ||
| }, | ||
| "build": { | ||
| "commit": "a1b2c3", | ||
| "created": "2019-04-29T10:00:00Z", | ||
| "duration": 60, | ||
| "error": "", | ||
| "finished": "2019-04-29T10:01:00Z", | ||
| "id": 1, | ||
| "project": "project", | ||
| "state": { | ||
| "code": "finished", | ||
| "name": "Finished" | ||
| }, | ||
|
There was a problem hiding this comment. This is probably commentary on the build serializer and not this PR, but I found myself wanting some helpers here around the build state data. The data is all here, but I had to replicate a good deal of backend logic to determine things like Consider this a side request I supposed 🙂 There was a problem hiding this comment. For example, I had to sort through a lot of build logic with the API response this the build detail view, for example: https://github.com/readthedocs/ext-theme/blob/main/src/js/build/detail.js#L236-L283 There was a problem hiding this comment.
This is a pretty common discussion between backend and frontend teams 😄 . IMHO, the data is there and it's the FE who should create "the helpers" required to present the data as they need --but I guess this is kind of a philosophical discussion. We can continue talking about this outside this PR. In any case, if we decide changing anything here, it should be done in the |
||
| "success": true, | ||
| "version": "latest" | ||
| }, | ||
| "domains": { | ||
| "dashboard": "readthedocs.org" | ||
| }, | ||
| "readthedocs": { | ||
| "analytics": { | ||
| "code": null | ||
| } | ||
| }, | ||
| "features": { | ||
| "analytics": { | ||
| "code": null | ||
| }, | ||
| "external_version_warning": { | ||
| "enabled": true, | ||
| "query_selector": "[role=main]" | ||
| }, | ||
| "non_latest_version_warning": { | ||
| "enabled": true, | ||
| "query_selector": "[role=main]", | ||
| "versions": [ | ||
| "latest" | ||
| ] | ||
| }, | ||
| "doc_diff": { | ||
| "enabled": true, | ||
| "base_url": "https://project.dev.readthedocs.io/en/latest/index.html", | ||
| "root_selector": "[role=main]", | ||
| "inject_styles": true, | ||
| "base_host": "", | ||
| "base_page": "" | ||
| }, | ||
| "flyout": { | ||
| "translations": [], | ||
| "versions": [ | ||
| {"slug": "latest", "url": "/en/latest/"} | ||
humitos marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ], | ||
| "downloads": [], | ||
| "vcs": { | ||
| "url": "https://github.com", | ||
| "username": "readthedocs", | ||
| "repository": "test-builds", | ||
| "branch": "a1b2c3", | ||
| "filepath": "/docs/index.rst" | ||
| } | ||
| }, | ||
| "search": { | ||
| "api_endpoint": "/_/api/v3/search/", | ||
| "default_filter": "subprojects:project/latest", | ||
| "filters": [ | ||
| ["Search only in this project", "project:project/latest"], | ||
| ["Search subprojects", "subprojects:project/latest"] | ||
|
There was a problem hiding this comment. I like this pattern. It also helps push the translations into the application which I like. Translations will be A Thing though, so we can punt on that conversation either way. There was a problem hiding this comment. Well, this is just a hard coded/default example. In theory, what I understood from the work that @stsewd did, is that the author of the docs is whom will decide the names and the values of the filters. So, we need to keep talking how that data will be passed (see readthedocs/addons#13) |
||
| ], | ||
| "project": "project", | ||
| "version": "latest" | ||
| } | ||
| } | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| { | ||
| "comment": "Undefined yet. Use v0 for now" | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| { | ||
| "error": "The version specified in 'X-RTD-Hosting-Integrations-Version' is currently not supported" | ||
| } |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
project.language.namehere is an example of where we could support a translated API response, probably based on accept headers. If the addition of a language aware API endpoint changes the implementation here drastically, maybe this is a now conversation. But I'm assuming it's not and we can come back to this as we give users more access into this response structure.