LukeParke/plex-api-spec
1
0
Fork 0
mirror of https://github.com/LukeHagar/plex-api-spec.git synced 2025-12-07 12:37:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

spruced and made some adjustments

Browse Source
This commit is contained in:
Luke Hagar
2024-09-11 18:23:13 +00:00
parent a525921b8e
commit 6e58229600
1 changed files with 31 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
README.md
View File

@@ -27,45 +27,54 @@ The following SDKs are generated from the OpenAPI Specification. They are automa
The main OpenAPI Specification is located in the root directory as [pms-spec.yaml](https://github.com/LukeHagar/plex-api-spec/blob/main/pms-spec.yaml). Which references The main OpenAPI Specification is located in the root directory as [pms-spec.yaml](https://github.com/LukeHagar/plex-api-spec/blob/main/pms-spec.yaml). Which references
- [**/paths**](https://github.com/LukeHagar/plex-api-spec/tree/main/paths): The endpoints for the Plex Media Server API. Each endpoint is defined in a separate file. - [**/paths**](https://github.com/LukeHagar/plex-api-spec/tree/main/paths): The endpoints for the Plex Media Server API. Each endpoint is defined in a separate file.
- [**/models**](https://github.com/LukeHagar/plex-api-spec/tree/main/models): The schema models used in the specification. - [**/models**](https://github.com/LukeHagar/plex-api-spec/tree/main/models): The schema models used in the specification.
- [**/parameters**](https://github.com/LukeHagar/plex-api-spec/tree/main/parameters): The parameters used in the specification. - [**/parameters**](https://github.com/LukeHagar/plex-api-spec/tree/main/parameters): The parameters used in the specification.
- [**/responses**](https://github.com/LukeHagar/plex-api-spec/tree/main/responses): The responses used in the specification. - [**/responses**](https://github.com/LukeHagar/plex-api-spec/tree/main/responses): The responses used in the specification.
In addition, there is a bundled single file OpenAPI Specification, [plex-media-server-spec-dereferenced.yaml](https://github.com/LukeHagar/plex-api-spec/blob/main/plex-media-server-spec-dereferenced.yaml) which is automatically bundled on any changes to the main specification. In addition, there is a bundled single file OpenAPI Specification, [plex-media-server-spec-dereferenced.yaml](https://github.com/LukeHagar/plex-api-spec/blob/main/plex-media-server-spec-dereferenced.yaml) which is automatically bundled on any changes to the main specification.
## Styleguide ## Style Guide
All spec files should adhere to the 3.1 OpenAPI Specification. All spec files should adhere to the 3.1 OpenAPI Specification.
Every endpoint is defined in the /paths directory. Each endpoint is defined in a separate file. The file name should be the endpoint name with the method type. For example, the endpoint /library/sections is defined in the file /paths/library_sections.get.yaml.
Reference documentation can be found [Here](https://www.speakeasy.com/openapi) and [Here](https://spec.openapis.org/oas/v3.1.0.html#openapi-specification).
Every endpoint is defined in the `/paths` directory, with Each endpoint defined in a separate file.
The file name should be the endpoint name with the method type. For example, the endpoint `/library/sections` is defined in the file `/paths/library_sections.get.yaml`.
The file should contain data in the following order: The file should contain data in the following order:
```yaml ```yaml
[get/post/put/delete]: [get/post/put/delete]:
servers: servers: # only specify if the endpoint requires a different server than the users plex server
security: security: # only specify if the endpoint requires authentication different from the global security
tags: tags:
summary: - example # a list of tags that the endpoint belongs to, this is used for grouping in the documentation and SDKs
description: summary: a brief description of the endpoint
operationId: lower snake case prefixed with the method type, post-user-sign-in-data description: a more detailed description of the endpoint
parameters: operationId: getLibrarySections # camel case summarizing the action being performed.
$ref: parameters: # parameters are defined in the /parameters directory, or inline if they are not reused very much
name: - $ref: "../../parameters/..." # a reference to a parameter file in the /parameters directory
description: - name: example # a parameter that is not a reference
required: in: query # the location of the parameter, can be query, path, header, or cookie
schema: description: an example parameter
required: true # whether the parameter is required or not, path parameters are always required. Only specify this key if the parameter is required
schema:
type: string
responses: responses:
2XX: 2XX:
$ref: "../../responses/..." # a reference to a response file in the /responses directory
4XX: 4XX:
5XX: 5XX:
``` ```
### Rules ### Rules
- A property in the response is only marked as required if it is always returned, regardless of the parameters sent with the request.
- Although Plex.tv API uses the `X-Plex-Token` as a query parameter, the specification will always define this as a header since this follows industry standard. - A property in the response is only marked as required if it is always returned, regardless of the parameters sent with the request.
- Although Plex.tv API uses the `X-Plex-Token` as a query parameter, this specification will always define this as a header parameter where supported since this follows industry security standards.
- Though Plex does default return `XML` unless the `accept` header is set to `application/json`, this specification will not include the `accept` header in the endpoints. Generally the accept value should come from the specified responses content type.
## Questions? ## Questions?
Reach out to me on the [Discord Server](https://discord.gg/mxqjsJHwUm) Reach out to me on the [Discord Server](https://discord.gg/mxqjsJHwUm)