From 67a908ffbfcac221bb6af0df6aa3030cdef056bf Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Sun, 22 Jan 2023 12:32:00 +0100 Subject: [PATCH 01/15] Create new "developers" docs section --- docs/developers/index.md | 6 ++++++ docusaurus.config.js | 9 +++++---- sidebars.js | 6 +++++- 3 files changed, 16 insertions(+), 5 deletions(-) create mode 100644 docs/developers/index.md diff --git a/docs/developers/index.md b/docs/developers/index.md new file mode 100644 index 000000000..293916dd5 --- /dev/null +++ b/docs/developers/index.md @@ -0,0 +1,6 @@ +--- +uid: intro +title: Developers +--- + +# Jellyfin developer documentation diff --git a/docusaurus.config.js b/docusaurus.config.js index 0192ec6db..1de854b0f 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -35,14 +35,15 @@ module.exports = { position: 'right' }, { - to: 'contribute', - label: 'Contribute', + type: 'doc', + docId: 'index', + label: 'Documentation', position: 'right' }, { type: 'doc', - docId: 'index', - label: 'Documentation', + docId: 'developers/index', + label: 'Developers', position: 'right' }, { diff --git a/sidebars.js b/sidebars.js index 2ec6ba976..b2bc05f24 100644 --- a/sidebars.js +++ b/sidebars.js @@ -14,7 +14,11 @@ module.exports = { docs: [ // "docs/general" pages 'index', - { type: 'autogenerated', dirName: 'general' }, + { type: 'autogenerated', dirName: 'general' } + ], + developers: [ + // "docs/developers" pages + { type: 'autogenerated', dirName: 'developers' }, { type: 'link', label: 'API Documentation', href: 'https://api.jellyfin.org' } ] }; From 5686fbe6e9294fb733945a848c9e33cb63582b12 Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Sun, 22 Jan 2023 12:34:51 +0100 Subject: [PATCH 02/15] Move current developer related documentation --- docs/{general/contributing => developers}/branding.md | 3 ++- docs/developers/contributing/_category_.yml | 2 ++ docs/{general => developers}/contributing/development.md | 0 docs/{general => developers}/contributing/index.md | 0 docs/{general => developers}/contributing/issues.md | 0 docs/{general => developers}/contributing/release-procedure.md | 0 docs/{general => developers}/contributing/source-tree.md | 0 docs/developers/index.md | 1 + docs/developers/style-guides/_category_.yml | 2 ++ docs/{general => developers}/style-guides/index.md | 0 docs/{general => developers}/style-guides/javascript.md | 0 11 files changed, 7 insertions(+), 1 deletion(-) rename docs/{general/contributing => developers}/branding.md (98%) create mode 100644 docs/developers/contributing/_category_.yml rename docs/{general => developers}/contributing/development.md (100%) rename docs/{general => developers}/contributing/index.md (100%) rename docs/{general => developers}/contributing/issues.md (100%) rename docs/{general => developers}/contributing/release-procedure.md (100%) rename docs/{general => developers}/contributing/source-tree.md (100%) create mode 100644 docs/developers/style-guides/_category_.yml rename docs/{general => developers}/style-guides/index.md (100%) rename docs/{general => developers}/style-guides/javascript.md (100%) diff --git a/docs/general/contributing/branding.md b/docs/developers/branding.md similarity index 98% rename from docs/general/contributing/branding.md rename to docs/developers/branding.md index 7680766a1..09fcdb155 100644 --- a/docs/general/contributing/branding.md +++ b/docs/developers/branding.md @@ -1,6 +1,7 @@ --- uid: contrib-branding -title: Branding +title: Jellyfin branding +sidebar_position: 2 --- # Branding diff --git a/docs/developers/contributing/_category_.yml b/docs/developers/contributing/_category_.yml new file mode 100644 index 000000000..ada9a24b5 --- /dev/null +++ b/docs/developers/contributing/_category_.yml @@ -0,0 +1,2 @@ +label: 'Contributing' +position: 3 diff --git a/docs/general/contributing/development.md b/docs/developers/contributing/development.md similarity index 100% rename from docs/general/contributing/development.md rename to docs/developers/contributing/development.md diff --git a/docs/general/contributing/index.md b/docs/developers/contributing/index.md similarity index 100% rename from docs/general/contributing/index.md rename to docs/developers/contributing/index.md diff --git a/docs/general/contributing/issues.md b/docs/developers/contributing/issues.md similarity index 100% rename from docs/general/contributing/issues.md rename to docs/developers/contributing/issues.md diff --git a/docs/general/contributing/release-procedure.md b/docs/developers/contributing/release-procedure.md similarity index 100% rename from docs/general/contributing/release-procedure.md rename to docs/developers/contributing/release-procedure.md diff --git a/docs/general/contributing/source-tree.md b/docs/developers/contributing/source-tree.md similarity index 100% rename from docs/general/contributing/source-tree.md rename to docs/developers/contributing/source-tree.md diff --git a/docs/developers/index.md b/docs/developers/index.md index 293916dd5..db9dc7289 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -1,6 +1,7 @@ --- uid: intro title: Developers +sidebar_position: 1 --- # Jellyfin developer documentation diff --git a/docs/developers/style-guides/_category_.yml b/docs/developers/style-guides/_category_.yml new file mode 100644 index 000000000..9addbbfa5 --- /dev/null +++ b/docs/developers/style-guides/_category_.yml @@ -0,0 +1,2 @@ +label: 'Style guides' +position: 4 diff --git a/docs/general/style-guides/index.md b/docs/developers/style-guides/index.md similarity index 100% rename from docs/general/style-guides/index.md rename to docs/developers/style-guides/index.md diff --git a/docs/general/style-guides/javascript.md b/docs/developers/style-guides/javascript.md similarity index 100% rename from docs/general/style-guides/javascript.md rename to docs/developers/style-guides/javascript.md From 309a9cffde7dc4084eeca46d5722a9b437cbbf25 Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Fri, 10 Feb 2023 22:13:02 +0100 Subject: [PATCH 03/15] Update header navigation --- docusaurus.config.js | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 1de854b0f..78d81358e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -28,21 +28,23 @@ module.exports = { src: 'images/logo.svg' }, items: [ - { to: 'posts', label: 'Blog', position: 'right' }, { to: 'downloads', - label: 'Downloads', - position: 'right' + label: 'Downloads' }, { - type: 'doc', - docId: 'index', - label: 'Documentation', - position: 'right' + to: 'posts', + label: 'Blog' + }, + { + type: 'docSidebar', + sidebarId: 'docs', + label: 'Documentation' }, + { - type: 'doc', - docId: 'developers/index', + type: 'docSidebar', + sidebarId: 'developers', label: 'Developers', position: 'right' }, From 0354eddb228c48146f1a41d5363a344771812821 Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Fri, 10 Feb 2023 21:54:26 +0100 Subject: [PATCH 04/15] Add documentation for API authorization to developers site --- docs/developers/api/_category_.yml | 2 + docs/developers/api/authorization.md | 64 +++++++++++++++++++++ docs/developers/branding.md | 2 +- docs/developers/contributing/_category_.yml | 2 +- docs/developers/style-guides/_category_.yml | 2 +- 5 files changed, 69 insertions(+), 3 deletions(-) create mode 100644 docs/developers/api/_category_.yml create mode 100644 docs/developers/api/authorization.md diff --git a/docs/developers/api/_category_.yml b/docs/developers/api/_category_.yml new file mode 100644 index 000000000..e8f9489e1 --- /dev/null +++ b/docs/developers/api/_category_.yml @@ -0,0 +1,2 @@ +label: 'HTTP API' +position: 2 diff --git a/docs/developers/api/authorization.md b/docs/developers/api/authorization.md new file mode 100644 index 000000000..cceec707f --- /dev/null +++ b/docs/developers/api/authorization.md @@ -0,0 +1,64 @@ +--- +title: Authorization +sidebar_position: 2 +--- + +# Jellyfin API Authorization + +To start using the Jellyfin API, authorization is probably the first thing you'll need to do. Jellyfin's authorization options can be a confusing because there are a lot of deprecated options. + +Generally there are three ways to authenticate: no authorization, user authorization with an access token or authorization with an API key. The first way is easy, just do nothing. But most often you'll need to use either the access token or API key. + +## Sending authorization values + +There are multiple methods for transmitting authorization values, however, some are outdated and scheduled to be removed. +It's recommend to use the `Authorization` header. If header auth isn't an option, the token should be sent trough the `ApiKey` query parameter. + +| Type | Name | Method | Deprecated | +| ------ | ---------------------- | ---------- | ---------- | +| Header | `Authorization` | Schema | No | +| Query | `ApiKey` | Token only | No | +| Query | `api_key` | Token only | **yes** | +| Header | `X-Emby-Token` | Token only | **yes** | +| Header | `X-MediaBrowser-Token` | Token only | **yes** | +| Header | `X-Emby-Authorization` | Schema | **yes** | + +Avoid sending multiple tokens in one request as it's uncertain which value will be used. Deprecated options may be removed in future server updates. + +## The Jellyfin authorization scheme + +The [Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) uses the format `Authorization: `. The Jellyfin scheme is named `MediaBrowser` and uses named values separated by commas. There is no specific order for parameters. A key can is case sensitive and only allows alphanumeric characters, unknown keys are ignored by the server. Values must be wrapped in double quotes (`"`) and should use [url encoding](https://en.wikipedia.org/wiki/URL_encoding). + +```txt +MediaBrowser key="value", key2="value2", key3="value3" +``` + +### Parameters + +| Key | Description | +| -------- | -------------------------------------------------- | +| Token | The access token or API key | +| Client | The name of the client | +| Version | The version of the client | +| DeviceId | A unique id for the device generated by the client | +| Device | The device name | + +The token parameter is required to use authenticated endpoints. The client and version properties are used to identify the client in the dashboard. + +### Examples + +- Authenticate with API key + + ```http + Authorization: MediaBrowser Token="8ac3a7abaff943ba9adea7f8754da7f8" + ``` + +- Authenticate with access token + + ```http + Authorization: MediaBrowser Token="0381cf931f9e42d79fb9c89f729167df", Client="Android TV", Device="Nvidia Shield", DeviceId="ZQ9YQHHrUzk24vV", Version="0.15.3" + ``` + +## The ApiKey query parameter + +Use the `ApiKey` query parameter when the `Authorization` header can't be used. The value of the query parameter is the access token or API key. Avoid using this option if possible. Never use the `ApiKey` query parameter and `Authorization` header at the same time. diff --git a/docs/developers/branding.md b/docs/developers/branding.md index 09fcdb155..f72af0347 100644 --- a/docs/developers/branding.md +++ b/docs/developers/branding.md @@ -1,7 +1,7 @@ --- uid: contrib-branding title: Jellyfin branding -sidebar_position: 2 +sidebar_position: 3 --- # Branding diff --git a/docs/developers/contributing/_category_.yml b/docs/developers/contributing/_category_.yml index ada9a24b5..26714ed4a 100644 --- a/docs/developers/contributing/_category_.yml +++ b/docs/developers/contributing/_category_.yml @@ -1,2 +1,2 @@ label: 'Contributing' -position: 3 +position: 4 diff --git a/docs/developers/style-guides/_category_.yml b/docs/developers/style-guides/_category_.yml index 9addbbfa5..77ee45643 100644 --- a/docs/developers/style-guides/_category_.yml +++ b/docs/developers/style-guides/_category_.yml @@ -1,2 +1,2 @@ label: 'Style guides' -position: 4 +position: 5 From fb1c4493e08c5ababba4fa66d49a2df1eadf2a1d Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Fri, 10 Feb 2023 21:59:26 +0100 Subject: [PATCH 05/15] Update title of authorization page --- docs/developers/api/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/api/authorization.md b/docs/developers/api/authorization.md index cceec707f..eeeb809fc 100644 --- a/docs/developers/api/authorization.md +++ b/docs/developers/api/authorization.md @@ -3,7 +3,7 @@ title: Authorization sidebar_position: 2 --- -# Jellyfin API Authorization +# Authorization To start using the Jellyfin API, authorization is probably the first thing you'll need to do. Jellyfin's authorization options can be a confusing because there are a lot of deprecated options. From abeaab27e5fcb45af21b14b84d9e5e671e4a7a30 Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Sat, 11 Feb 2023 15:10:07 +0100 Subject: [PATCH 06/15] Replace @docusaurus/preset-classic with manual plugin configurations --- docusaurus.config.js | 14 ++++++++++++-- package.json | 2 +- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 78d81358e..b29c85b7b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -97,7 +97,6 @@ Site content is licensed Date: Sat, 11 Feb 2023 20:04:32 +0100 Subject: [PATCH 07/15] Redo folder structure and paths for developer site, add blog/pages/docs plugins --- content/developers/docs/_sidebar.js | 6 +++ .../developers/docs}/api/_category_.yml | 0 .../developers/docs}/api/authorization.md | 0 .../developers/docs}/branding.md | 0 .../docs}/contributing/_category_.yml | 0 .../docs}/contributing/development.md | 0 .../developers/docs}/contributing/index.md | 0 .../developers/docs}/contributing/issues.md | 0 .../docs}/contributing/release-procedure.md | 0 .../docs}/contributing/source-tree.md | 0 .../developers/docs}/index.md | 2 +- .../docs}/style-guides/_category_.yml | 0 .../developers/docs}/style-guides/index.md | 0 .../docs}/style-guides/javascript.md | 0 docusaurus.config.js | 49 +++++++++++++------ sidebars.js | 5 -- 16 files changed, 42 insertions(+), 20 deletions(-) create mode 100644 content/developers/docs/_sidebar.js rename {docs/developers => content/developers/docs}/api/_category_.yml (100%) rename {docs/developers => content/developers/docs}/api/authorization.md (100%) rename {docs/developers => content/developers/docs}/branding.md (100%) rename {docs/developers => content/developers/docs}/contributing/_category_.yml (100%) rename {docs/developers => content/developers/docs}/contributing/development.md (100%) rename {docs/developers => content/developers/docs}/contributing/index.md (100%) rename {docs/developers => content/developers/docs}/contributing/issues.md (100%) rename {docs/developers => content/developers/docs}/contributing/release-procedure.md (100%) rename {docs/developers => content/developers/docs}/contributing/source-tree.md (100%) rename {docs/developers => content/developers/docs}/index.md (78%) rename {docs/developers => content/developers/docs}/style-guides/_category_.yml (100%) rename {docs/developers => content/developers/docs}/style-guides/index.md (100%) rename {docs/developers => content/developers/docs}/style-guides/javascript.md (100%) diff --git a/content/developers/docs/_sidebar.js b/content/developers/docs/_sidebar.js new file mode 100644 index 000000000..8726089f0 --- /dev/null +++ b/content/developers/docs/_sidebar.js @@ -0,0 +1,6 @@ +module.exports = { + developers: [ + { type: 'autogenerated', dirName: '.' }, + { type: 'link', label: 'API Documentation', href: 'https://api.jellyfin.org' } + ] +}; diff --git a/docs/developers/api/_category_.yml b/content/developers/docs/api/_category_.yml similarity index 100% rename from docs/developers/api/_category_.yml rename to content/developers/docs/api/_category_.yml diff --git a/docs/developers/api/authorization.md b/content/developers/docs/api/authorization.md similarity index 100% rename from docs/developers/api/authorization.md rename to content/developers/docs/api/authorization.md diff --git a/docs/developers/branding.md b/content/developers/docs/branding.md similarity index 100% rename from docs/developers/branding.md rename to content/developers/docs/branding.md diff --git a/docs/developers/contributing/_category_.yml b/content/developers/docs/contributing/_category_.yml similarity index 100% rename from docs/developers/contributing/_category_.yml rename to content/developers/docs/contributing/_category_.yml diff --git a/docs/developers/contributing/development.md b/content/developers/docs/contributing/development.md similarity index 100% rename from docs/developers/contributing/development.md rename to content/developers/docs/contributing/development.md diff --git a/docs/developers/contributing/index.md b/content/developers/docs/contributing/index.md similarity index 100% rename from docs/developers/contributing/index.md rename to content/developers/docs/contributing/index.md diff --git a/docs/developers/contributing/issues.md b/content/developers/docs/contributing/issues.md similarity index 100% rename from docs/developers/contributing/issues.md rename to content/developers/docs/contributing/issues.md diff --git a/docs/developers/contributing/release-procedure.md b/content/developers/docs/contributing/release-procedure.md similarity index 100% rename from docs/developers/contributing/release-procedure.md rename to content/developers/docs/contributing/release-procedure.md diff --git a/docs/developers/contributing/source-tree.md b/content/developers/docs/contributing/source-tree.md similarity index 100% rename from docs/developers/contributing/source-tree.md rename to content/developers/docs/contributing/source-tree.md diff --git a/docs/developers/index.md b/content/developers/docs/index.md similarity index 78% rename from docs/developers/index.md rename to content/developers/docs/index.md index db9dc7289..8feb22775 100644 --- a/docs/developers/index.md +++ b/content/developers/docs/index.md @@ -1,5 +1,5 @@ --- -uid: intro +uid: developers-index title: Developers sidebar_position: 1 --- diff --git a/docs/developers/style-guides/_category_.yml b/content/developers/docs/style-guides/_category_.yml similarity index 100% rename from docs/developers/style-guides/_category_.yml rename to content/developers/docs/style-guides/_category_.yml diff --git a/docs/developers/style-guides/index.md b/content/developers/docs/style-guides/index.md similarity index 100% rename from docs/developers/style-guides/index.md rename to content/developers/docs/style-guides/index.md diff --git a/docs/developers/style-guides/javascript.md b/content/developers/docs/style-guides/javascript.md similarity index 100% rename from docs/developers/style-guides/javascript.md rename to content/developers/docs/style-guides/javascript.md diff --git a/docusaurus.config.js b/docusaurus.config.js index b29c85b7b..6054cfb2e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -43,8 +43,7 @@ module.exports = { }, { - type: 'docSidebar', - sidebarId: 'developers', + to: 'developers/docs/', label: 'Developers', position: 'right' }, @@ -97,6 +96,7 @@ Site content is licensed Date: Sat, 11 Feb 2023 22:54:42 +0100 Subject: [PATCH 08/15] Add redirects for developer documents moved from main docs --- redirects.js | 33 +++++++++++++++++++++++++++++++++ src/pages/contribute.tsx | 2 +- 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/redirects.js b/redirects.js index 8cd5b4936..4b4555db0 100644 --- a/redirects.js +++ b/redirects.js @@ -36,5 +36,38 @@ module.exports = [ { from: '/docs/general/administration/building', to: '/docs/general/installation/source' + }, + // New developer site + { + from: '/docs/general/contributing/branding', + to: '/developers/docs/branding' + }, + { + from: '/docs/general/contributing/', + to: '/developers/docs/contributing/' + }, + { + from: '/docs/general/contributing/development', + to: '/developers/docs/contributing/development' + }, + { + from: '/docs/general/contributing/issues', + to: '/developers/docs/contributing/issues' + }, + { + from: '/docs/general/contributing/release-procedure', + to: '/developers/docs/contributing/release-procedure' + }, + { + from: '/docs/general/contributing/source-tree', + to: '/developers/docs/contributing/source-tree' + }, + { + from: '/docs/general/style-guides/', + to: '/developers/docs/style-guides/' + }, + { + from: '/docs/general/style-guides/javascript', + to: '/developers/docs/style-guides/javascript' } ]; diff --git a/src/pages/contribute.tsx b/src/pages/contribute.tsx index dd328e55d..931d3381f 100644 --- a/src/pages/contribute.tsx +++ b/src/pages/contribute.tsx @@ -29,7 +29,7 @@ export default function Contribute() {

Before contributing, please read over our{' '} Community Standards and  - Contributing Guide. + Contributing Guide.

From 4699bc676112cba6e0ef62fcf835c01ce6e0dd66 Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Sat, 18 Mar 2023 14:44:59 +0100 Subject: [PATCH 09/15] Add index page for developers site --- content/developers/docs/index.md | 7 --- content/developers/pages/index.scss | 16 ++++++ content/developers/pages/index.tsx | 86 +++++++++++++++++++++++++++++ docusaurus.config.js | 2 +- 4 files changed, 103 insertions(+), 8 deletions(-) delete mode 100644 content/developers/docs/index.md create mode 100644 content/developers/pages/index.scss create mode 100644 content/developers/pages/index.tsx diff --git a/content/developers/docs/index.md b/content/developers/docs/index.md deleted file mode 100644 index 8feb22775..000000000 --- a/content/developers/docs/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -uid: developers-index -title: Developers -sidebar_position: 1 ---- - -# Jellyfin developer documentation diff --git a/content/developers/pages/index.scss b/content/developers/pages/index.scss new file mode 100644 index 000000000..0812805f9 --- /dev/null +++ b/content/developers/pages/index.scss @@ -0,0 +1,16 @@ +.card--dev-index { + h2 { + margin: 10px 20px 0 20px; + } + + ul { + padding: 0; + list-style: none; + margin: 10px 10px 0 10px; + + li a { + display: block; + padding: 10px; + } + } +} diff --git a/content/developers/pages/index.tsx b/content/developers/pages/index.tsx new file mode 100644 index 000000000..9085a7a9e --- /dev/null +++ b/content/developers/pages/index.tsx @@ -0,0 +1,86 @@ +import React, { ReactNode } from 'react'; +import Layout from '@theme/Layout'; +import Link from '@docusaurus/Link'; +import Hero from '../../../src/components/common/Hero'; +import blogPosts from '../../../.docusaurus/docusaurus-plugin-content-blog/developers-blog/blog-post-list-prop-developers-blog.json'; + +import './index.scss'; + +function Section({ title, children }: { title: string; children: ReactNode }) { + return ( +
+
+

{title}

+ {children} +
+
+ ); +} + +function DocsHighlights() { + return ( +
+
    +
  • + Using the REST API +
    • +
  • + Creating a server plugin +
    • +
+
+ ); +} + +function OtherPages() { + return ( +
+
    +
  • + Contributing +
    • +
  • + Jellyfin branding +
    • +
+
+ ); +} + +function RecentBlogPosts() { + return ( +
+ +
+ ); +} + +function Index() { + return ( + + +

Get started developing with or for Jellyfin today.

+
+ Not a developer? Go to the user documentation +
+ +
+
+
+ + + +
+
+
+ + ); +} + +export default Index; diff --git a/docusaurus.config.js b/docusaurus.config.js index 6054cfb2e..9e6e975b2 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -43,7 +43,7 @@ module.exports = { }, { - to: 'developers/docs/', + to: 'developers', label: 'Developers', position: 'right' }, From 481626b8657abb20d69d91de8ecb35fe8621d8f4 Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Mon, 27 Nov 2023 19:24:17 +0100 Subject: [PATCH 10/15] Fix missing new line --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index c5e8ecb4f..3edddf1c6 100644 --- a/package.json +++ b/package.json @@ -80,4 +80,4 @@ "typescript": "5.3.2", "typescript-plugin-css-modules": "5.0.2" } -} \ No newline at end of file +} From 19825218ca526684cdcd3b47ffe5ec6d5a3090a3 Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Thu, 7 Mar 2024 21:06:01 +0100 Subject: [PATCH 11/15] Update authorization documentation to latest gist revision --- content/developers/docs/api/authorization.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/content/developers/docs/api/authorization.md b/content/developers/docs/api/authorization.md index eeeb809fc..2990de29e 100644 --- a/content/developers/docs/api/authorization.md +++ b/content/developers/docs/api/authorization.md @@ -5,14 +5,14 @@ sidebar_position: 2 # Authorization -To start using the Jellyfin API, authorization is probably the first thing you'll need to do. Jellyfin's authorization options can be a confusing because there are a lot of deprecated options. +To start using the Jellyfin API, authorization is probably the first thing you'll need to do. Jellyfin's authorization options can be a bit confusing because there are a lot of deprecated options. Generally there are three ways to authenticate: no authorization, user authorization with an access token or authorization with an API key. The first way is easy, just do nothing. But most often you'll need to use either the access token or API key. ## Sending authorization values There are multiple methods for transmitting authorization values, however, some are outdated and scheduled to be removed. -It's recommend to use the `Authorization` header. If header auth isn't an option, the token should be sent trough the `ApiKey` query parameter. +It's recommend to use the `Authorization` header. If header auth isn't an option, the token should be sent through the `ApiKey` query parameter. | Type | Name | Method | Deprecated | | ------ | ---------------------- | ---------- | ---------- | @@ -23,11 +23,11 @@ It's recommend to use the `Authorization` header. If header auth isn't an option | Header | `X-MediaBrowser-Token` | Token only | **yes** | | Header | `X-Emby-Authorization` | Schema | **yes** | -Avoid sending multiple tokens in one request as it's uncertain which value will be used. Deprecated options may be removed in future server updates. +Avoid sending multiple tokens in one request as it's uncertain which value will be used. Deprecated options might be removed in future server updates. ## The Jellyfin authorization scheme -The [Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) uses the format `Authorization: `. The Jellyfin scheme is named `MediaBrowser` and uses named values separated by commas. There is no specific order for parameters. A key can is case sensitive and only allows alphanumeric characters, unknown keys are ignored by the server. Values must be wrapped in double quotes (`"`) and should use [url encoding](https://en.wikipedia.org/wiki/URL_encoding). +The [Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) uses the format `Authorization: `. The Jellyfin scheme is named `MediaBrowser` and it uses named values separated by commas. There is no specific order for parameters. All keys are case sensitive and only allow alphanumeric characters. Unknown keys are ignored by the server. Values must be wrapped in double quotes (`"`) and should use [url encoding](https://en.wikipedia.org/wiki/URL_encoding). ```txt MediaBrowser key="value", key2="value2", key3="value3" @@ -45,8 +45,16 @@ MediaBrowser key="value", key2="value2", key3="value3" The token parameter is required to use authenticated endpoints. The client and version properties are used to identify the client in the dashboard. +#### Device identifiers + +When it comes to device identifiers in the Jellyfin API, it's important to understand the nuances involved. While generating a random string for the `deviceId` might seem like a straightforward solution, there are certain limitations to consider. Currently, the server permits only a single access token for each `deviceId`. This means that you cannot have multiple users signed into your client with a single randomized string. To work around this limitation, you'll need to use a unique identifier for each combination of a device-specific identifier and user-specific identifier. + +Since it's often not possible to know the user identifier before signing in at least once, we recommend including the username as user-specific identifier. It is advisable to hash the username because it is user-input that could include double quotes (escaping the header value format) or special characters that your HTTP library might not allow. + ### Examples +Here are a couple of examples for the authorization header: + - Authenticate with API key ```http @@ -61,4 +69,4 @@ The token parameter is required to use authenticated endpoints. The client and v ## The ApiKey query parameter -Use the `ApiKey` query parameter when the `Authorization` header can't be used. The value of the query parameter is the access token or API key. Avoid using this option if possible. Never use the `ApiKey` query parameter and `Authorization` header at the same time. +Use the `ApiKey` query parameter when the `Authorization` header can't be used. The value of the query parameter is the access token or API key. Avoid using this option if possible. Never use the `ApiKey` query parameter and the `Authorization` header at the same time. From 0b5c85163502b47cd478c3e23a2e00d742128cc5 Mon Sep 17 00:00:00 2001 From: Peaches_MLG Date: Thu, 7 Mar 2024 21:48:52 +0000 Subject: [PATCH 12/15] Added a work in progress banner under the /developers page --- src/components/banner/Banner.scss | 5 +++++ src/components/banner/Banner.tsx | 14 ++++++++++++++ src/theme/Root.tsx | 13 +++++++++++++ 3 files changed, 32 insertions(+) create mode 100644 src/components/banner/Banner.scss create mode 100644 src/components/banner/Banner.tsx create mode 100644 src/theme/Root.tsx diff --git a/src/components/banner/Banner.scss b/src/components/banner/Banner.scss new file mode 100644 index 000000000..2fcce6799 --- /dev/null +++ b/src/components/banner/Banner.scss @@ -0,0 +1,5 @@ +.banner { + background-color: #007ca6; + padding: 10px; + text-align: center; +} \ No newline at end of file diff --git a/src/components/banner/Banner.tsx b/src/components/banner/Banner.tsx new file mode 100644 index 000000000..6cc24fd99 --- /dev/null +++ b/src/components/banner/Banner.tsx @@ -0,0 +1,14 @@ +import React from 'react'; + +import './Banner.scss'; + +function Banner({ text }: { text: string }) { + return ( +
+ {text} +
+ ); +} + +export default Banner; + diff --git a/src/theme/Root.tsx b/src/theme/Root.tsx new file mode 100644 index 000000000..0980d3df8 --- /dev/null +++ b/src/theme/Root.tsx @@ -0,0 +1,13 @@ +import React from 'react'; +import { useLocation } from '@docusaurus/router'; +import Banner from '../components/banner/Banner'; + +// The root view wrapper for the entire app +export default function Root({ children }: { children: React.ReactNode }) { + const isInDevelopersSection = useLocation().pathname.startsWith('/developers'); + + return <> + {isInDevelopersSection && } + {children} + ; +} \ No newline at end of file From a9e73a8a7e2bbfcbab9eca2e9dcad42f419ef81b Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Mon, 11 Mar 2024 19:16:09 +0100 Subject: [PATCH 13/15] Reformat + update text --- src/components/banner/Banner.scss | 2 +- src/components/banner/Banner.tsx | 7 +------ src/theme/Root.tsx | 18 ++++++++++++------ 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/src/components/banner/Banner.scss b/src/components/banner/Banner.scss index 2fcce6799..d63cc1244 100644 --- a/src/components/banner/Banner.scss +++ b/src/components/banner/Banner.scss @@ -2,4 +2,4 @@ background-color: #007ca6; padding: 10px; text-align: center; -} \ No newline at end of file +} diff --git a/src/components/banner/Banner.tsx b/src/components/banner/Banner.tsx index 6cc24fd99..a99afce12 100644 --- a/src/components/banner/Banner.tsx +++ b/src/components/banner/Banner.tsx @@ -3,12 +3,7 @@ import React from 'react'; import './Banner.scss'; function Banner({ text }: { text: string }) { - return ( -
- {text} -
- ); + return
{text}
; } export default Banner; - diff --git a/src/theme/Root.tsx b/src/theme/Root.tsx index 0980d3df8..e49966d2d 100644 --- a/src/theme/Root.tsx +++ b/src/theme/Root.tsx @@ -2,12 +2,18 @@ import React from 'react'; import { useLocation } from '@docusaurus/router'; import Banner from '../components/banner/Banner'; -// The root view wrapper for the entire app +/** + * The root view wrapper for the entire app. + */ export default function Root({ children }: { children: React.ReactNode }) { const isInDevelopersSection = useLocation().pathname.startsWith('/developers'); - return <> - {isInDevelopersSection && } - {children} - ; -} \ No newline at end of file + return ( + <> + {isInDevelopersSection && ( + + )} + {children} + + ); +} From c5c8a15d5fe3142b52a6cb0981bda7810ea29fbd Mon Sep 17 00:00:00 2001 From: Niels van Velzen Date: Tue, 12 Mar 2024 11:19:18 +0100 Subject: [PATCH 14/15] Update CODEOWNERS --- .github/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e80b79216..b2eaa00d7 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,3 +1,4 @@ blog/ @jellyfin/core docs/general/about.md @jellyfin/core docs/general/community-standards.md @joshuaboniface +content/developers/ @nielsvanvelzen From 8987880183821d92f58bb1541f87f8bbcb8add61 Mon Sep 17 00:00:00 2001 From: Peaches_MLG Date: Sat, 16 Mar 2024 14:27:23 +0000 Subject: [PATCH 15/15] Refactor code to reduce duplication (#895) * Refactor code to reduce duplication * Reformat using prettier --- content/developers/pages/index.tsx | 87 ++++++------------- .../navigationLinks/NavigationLinks.tsx | 23 +++++ src/components/section/Section.tsx | 12 +++ 3 files changed, 60 insertions(+), 62 deletions(-) create mode 100644 src/components/navigationLinks/NavigationLinks.tsx create mode 100644 src/components/section/Section.tsx diff --git a/content/developers/pages/index.tsx b/content/developers/pages/index.tsx index 9085a7a9e..920628a72 100644 --- a/content/developers/pages/index.tsx +++ b/content/developers/pages/index.tsx @@ -1,67 +1,13 @@ -import React, { ReactNode } from 'react'; +import React from 'react'; import Layout from '@theme/Layout'; import Link from '@docusaurus/Link'; import Hero from '../../../src/components/common/Hero'; import blogPosts from '../../../.docusaurus/docusaurus-plugin-content-blog/developers-blog/blog-post-list-prop-developers-blog.json'; import './index.scss'; +import NavigationLinks from '../../../src/components/navigationLinks/NavigationLinks'; -function Section({ title, children }: { title: string; children: ReactNode }) { - return ( -
-
-

{title}

- {children} -
-
- ); -} - -function DocsHighlights() { - return ( -
-
    -
  • - Using the REST API -
    • -
  • - Creating a server plugin -
    • -
-
- ); -} - -function OtherPages() { - return ( -
-
    -
  • - Contributing -
    • -
  • - Jellyfin branding -
    • -
-
- ); -} - -function RecentBlogPosts() { - return ( -
-
    - {blogPosts.items.slice(0, 5).map((item, index) => ( -
  • - {item.title}{' '} -
    • - ))} -
-
- ); -} - -function Index() { +export default function Index() { return ( @@ -73,14 +19,31 @@ function Index() {
- - - + + + { + return { url: item.permalink, name: item.title }; + })} + /> + +
); } - -export default Index; diff --git a/src/components/navigationLinks/NavigationLinks.tsx b/src/components/navigationLinks/NavigationLinks.tsx new file mode 100644 index 000000000..7e0d8931b --- /dev/null +++ b/src/components/navigationLinks/NavigationLinks.tsx @@ -0,0 +1,23 @@ +import React from 'react'; + +import Section from '../section/Section'; +import Link from '@docusaurus/Link'; + +interface Page { + url: string; + name: string; +} + +export default function NavigationLinks({ title, pages }: { title: string; pages: Page[] }) { + return ( +
+
    + {pages.map((page, index) => ( +
  • + {page.name} +
    • + ))} +
+
+ ); +} diff --git a/src/components/section/Section.tsx b/src/components/section/Section.tsx new file mode 100644 index 000000000..1aa7e2e8c --- /dev/null +++ b/src/components/section/Section.tsx @@ -0,0 +1,12 @@ +import React, { ReactNode } from 'react'; + +export default function Section({ title, children }: { title: string; children: ReactNode }) { + return ( +
+
+

{title}

+ {children} +
+
+ ); +}