-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: add initial versioning endpoints
- Loading branch information
Showing
7 changed files
with
332 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| --- | ||
| title: Get supported capabilities | ||
| description: Query a server for its supported capabilities | ||
| sidebar: | ||
| order: 3 | ||
| --- | ||
|
|
||
| import CoreAction from "@partials/_core-action.mdx"; | ||
|
|
||
| <CoreAction /> | ||
|
|
||
| ``` | ||
| GET /{major_version}/capabilities | ||
| ``` | ||
|
|
||
| This endpoint informs clients of all capabilities supported by the server. This information MUST inform the client of any supported **optional** features as well as any configuration options associated with them. | ||
|
|
||
| Each capability is returned as an **object** containing key-value pairs representing the capability's settings. Clients SHOULD use this information to adjust their behavior. | ||
|
|
||
| ## Parameters | ||
|
|
||
| | Field | Type | In | Required? | Description | | ||
| | --------------- | ------ | ---- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `major_version` | String | Path | Yes | The **major** version that the client wants to target. <br /> The server MUST return all supported features for **each** major version. | | ||
|
|
||
| ## Client behavior | ||
|
|
||
| Clients SHOULD inform the user which features are supported by the server. Clients MAY also display information about relevant settings. | ||
|
|
||
| ## Server behavior | ||
|
|
||
| The server MUST respond with all supported **optional** features and any associated settings. If a feature isn't enabled, the server MUST NOT include it in the response. | ||
|
|
||
| ## Example request | ||
|
|
||
| <Tabs> | ||
| <TabItem label="JSON"> | ||
|
|
||
| ```console | ||
| $ curl -X 'GET' \ | ||
| '/v1/capabilities' \ | ||
| -H 'accept: application/json' | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem label="XML"> | ||
|
|
||
| ```console | ||
| $ curl -X 'GET' \ | ||
| '/v1/capabilities' \ | ||
| -H 'accept: application/xml' | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| <Tabs> | ||
| <TabItem label="JSON"> | ||
|
|
||
| ```json | ||
| { | ||
| "capabilities": { | ||
| "queue_sync": { | ||
| "max_queues": 5 | ||
| }, | ||
| "store_shows": {}, | ||
| "store_episodes": { | ||
| "allow": true, | ||
| "upload_quota": 500 | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem label="XML"> | ||
|
|
||
| ```xml | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <root> | ||
| <capabilities> | ||
| <queue_sync> | ||
| <max_queues>5</max_queues> | ||
| </queue_sync> | ||
| <store_shows> | ||
| </store_shows> | ||
| <store_episodes> | ||
| <allow>true</allow> | ||
| <upload_quota>500</upload_quota> | ||
| </store_episodes> | ||
| </capabilities> | ||
| </root> | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| --- | ||
| title: Get supported versions | ||
| description: Query a server for its supported versions | ||
| sidebar: | ||
| order: 2 | ||
| --- | ||
|
|
||
| import CoreAction from "@partials/_core-action.mdx"; | ||
|
|
||
| <CoreAction /> | ||
|
|
||
| ``` | ||
| GET /versions | ||
| ``` | ||
|
|
||
| This endpoint returns an array of versions supported by the server. This informs the client what **core** features are supported. The array MUST contain an entry for each **major** version supported by the server. | ||
|
|
||
| Versions follow the following format: | ||
|
|
||
| ``` | ||
| v{major_version}.{minor_version} | ||
| ``` | ||
|
|
||
| :::note | ||
| The `minor_version` MUST reflect the **highest** minor version supported by the server. | ||
| ::: | ||
|
|
||
| | Field | Type | Required? | Description | | ||
| | ---------- | --------------- | --------- | ---------------------------- | | ||
| | `versions` | Array\<String\> | Yes | A list of supported versions | | ||
|
|
||
| ## Client behavior | ||
|
|
||
| Clients SHOULD use the version number to adjust their behavior. For example, if the client is built with support for **v1.4** of the spec, and the server supports up to **v1.2**, the client should modify its calls to ensure they are compatible with **v1.2**. | ||
|
|
||
| ## Server behavior | ||
|
|
||
| Servers MUST respond with all fields, including deprecated fields, to ensure that older clients can interpret the response properly. | ||
|
|
||
| ## Example request | ||
|
|
||
| <Tabs> | ||
| <TabItem label="JSON"> | ||
|
|
||
| ```console | ||
| $ curl -X 'GET' \ | ||
| '/versions' \ | ||
| -H 'accept: application/json' | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem label="XML"> | ||
|
|
||
| ```console | ||
| $ curl -X 'GET' \ | ||
| '/versions' \ | ||
| -H 'accept: application/xml' | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| <Tabs> | ||
| <TabItem label="JSON"> | ||
|
|
||
| ```json | ||
| [ | ||
| "v1.1", | ||
| "v2.0" | ||
| ] | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem label="XML"> | ||
|
|
||
| ```xml | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <versions> | ||
| <version>v1.1</version> | ||
| <version>v2.0</version> | ||
| </versions> | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| --- | ||
| title: API versioning | ||
| description: Details about how the API is versioned | ||
| prev: false | ||
| sidebar: | ||
| label: Versioning | ||
| order: 1 | ||
| --- | ||
|
|
||
| The Open Podcast API is subject to change over time. To ensure backwards compatibility and effective communication of server capabilities, the API specification MUST be versioned in a consistent way. | ||
|
|
||
| The specification follows the [Semantic versioning model](https://semver.org/). Each version of the specification MUST adhere to the following rules: | ||
|
|
||
| **Major** versions | ||
| : A major version update indicates that a breaking change has occured. This is reserved for the deprecation, addition, or renaming of **core** capabilities. | ||
|
|
||
| **Minor** versions | ||
| : A minor version update indicates that a new **optional** feature has been added or that a **core** feature has received a non-breaking change. This can include the deprecation or addition of parameters or behaviors. | ||
|
|
||
| **Patch** versions | ||
| : A patch version update indicates that a small non-breaking change has been made to clarify a feature or address an issue with wording. | ||
|
|
||
| ## Backwards compatibility | ||
|
|
||
| To maintain backwards compatibility between **minor** versions, no parameters nor endpoints may be removed without a **major** version change. Fields may be deprecated in favor of new behaviors, but when queried by an older client the server MUST respond with a compatible response. |