From c860b4e2b728874029b52cccfd84324a93f708a1 Mon Sep 17 00:00:00 2001 From: Daniel Mason Date: Sat, 25 Dec 2021 17:27:35 +1300 Subject: [PATCH] Update API docs --- docs/api/build/index.html | 470 +++++++++++++++++++- docs/api/source/includes/_admin.md | 70 +++ docs/api/source/includes/_authentication.md | 62 ++- docs/api/source/includes/_errors.md | 22 - docs/api/source/includes/_ingress.md | 109 +++++ docs/api/source/includes/_introduction.md | 2 +- docs/api/source/includes/_ratelimits.md | 13 + docs/api/source/includes/_serverinfo.md | 2 +- docs/api/source/index.html.md | 3 + 9 files changed, 714 insertions(+), 39 deletions(-) create mode 100644 docs/api/source/includes/_admin.md delete mode 100644 docs/api/source/includes/_errors.md create mode 100644 docs/api/source/includes/_ingress.md create mode 100644 docs/api/source/includes/_ratelimits.md diff --git a/docs/api/build/index.html b/docs/api/build/index.html index 42658971..1caefa2c 100644 --- a/docs/api/build/index.html +++ b/docs/api/build/index.html @@ -315,11 +315,25 @@
  • Introduction
    • +
  • + Rate Limits +
  • Server Info +
    • +
  • + Ingress Endpoints +
    • @@ -327,16 +341,30 @@ Authentication + +
  • + Admin Endpoints +
    • @@ -353,8 +381,20 @@

    Introduction

    Welcome to the GoScrobble API documentation.

    -

    The majority of these API endpoints are public with reasonable rate limits.

    -

    Server Info

    v1/serverinfo

    +

    The majority of these API endpoints are public with rate limiting and do not require authentication.

    +

    Rate Limits

    +

    There are 3 tiers of rate-limiting:
    +Light rate-limiting: 1 request per 4 seconds with a max burst of 2.
    +Standard rate-limiting: 5 requests per second with a burst of 5.
    +Heavy rate-limiting: 10 requests per second with a burst of 10.

    + +

    The rate limits work as a 'bucket' system where there is a max (burst) and a regenerative rate. More info can be found in the source file server_middleware.go.

    + +

    Each endpoint will depict which rate limit applies.

    + +

    For example: +On the medium rate-limiter, you start with 5 requests available to you instantly, and this replenishes 5 requests per second.

    +

    Server Info

    GET v1/serverinfo

    Check server version and registration status:

    @@ -371,12 +411,299 @@

    This endpoint is used to get server API version and registration status.

    HTTP Request

    GET https://goscrobble.com/api/v1/serverstatus

    -

    Authentication

    v1/login

    +

    Ingress Endpoints

    +

    Spotify and Navidrome both work on a poll based system and do not require incoming webhooks/endpoints.

    +

    POST v1/ingress/jellyfin

    +
    +

    Submit a scrobble:

    +
    +
    curl "https://goscrobble.com/api/v1/ingress/jellyfin" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \
+  -X POST \
+  --data '{"Name":"<Full JSON structure located in ingress_jellyfin.go>", "Album":"Best Album","Artist":"Best Artist"}'
+
    +
    +

    Response:

    +
    +
    {
+  "message": "success"
+}
+
    +

    Adds a scrobble from Jellyfin into the database. Please view type JellyfinRequest struct in ingress_jellyfin.go for the full request format. You need to install the webhook plugin for this to work.

    + + +

    HTTP Request

    +

    POST https://goscrobble.com/api/v1/ingress/jellyfin

    +

    Query Parameters

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ParameterRequiredTypeDescription
    AlbumtruestringAlbum title
    ArtisttruestringArtist name
    NametruestringSong title
    ItemTypetruestringWill only scrobble type 'Audio'
    ClientNamefalsestringTBD
    DeviceIdfalsestringTBD
    DeviceNamefalsestringTBD
    IsAutomatedfalseboolTBD
    IsPausedfalseboolTBD
    ItemIdfalsestringTBD
    MediaSourceIdfalsestringTBD
    NotificationTypefalsestringTBD
    OverviewfalsestringTBD
    PlaybackPositionfalsestringTBD
    PlaybackPositionTicksfalseintTBD
    Provider_musicbrainzalbumfalsestringTBD
    Provider_musicbrainzalbumartistfalsestringTBD
    Provider_musicbrainzartistfalsestringTBD
    Provider_musicbrainzreleasegroupfalsestringTBD
    Provider_musicbrainztrackfalsestringTBD
    RunTimefalsestringTBD
    RunTimeTicksfalseintTBD
    ServerIdfalsestringTBD
    ServerNamefalsestringTBD
    ServerUrlfalsestringTBD
    ServerVersionfalsestringTBD
    TimestampfalsestringTBD
    UserIdfalseTBD
    UsernamefalseTBD
    UtcTimestampfalseTBD
    YearfalseintTBD
    +

    POST v1/ingress/multiscrobbler

    +
    +

    Submit a scrobble:

    +
    +
    curl "https://goscrobble.com/api/v1/ingress/multiscrobbler" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \
+  -X POST \
+  --data '{"Track":"<Full JSON structure located in ingress_multiscrobbler.go>", "Album":"Best Album","Artist":["Best Artist1", "Best Artist2"]}'
+
    +
    +

    Response:

    +
    +
    {
+  "message": "success"
+}
+
    +

    Adds a scrobble from MultiScrobbler into the database. Please view type MultiScrobblerRequest struct in ingress_multiscrobbler.go for the full request format.

    + + +

    HTTP Request

    +

    POST https://goscrobble.com/api/v1/ingress/multiscrobbler

    +

    Query Parameters

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ParameterRequiredTypeDescription
    AlbumtruestringAlbum title
    ArtisttruearrayArray of Artist names
    TracktruestringSong title
    PlayedAttrueintUnix Timestamp of scrobble time
    DurationtrueintSong length in seconds
    +

    Authentication

    POST v1/login

    To obtain a JWT token (Replace default credentials):

    curl "https://goscrobble.com/api/v1/login" \
   -H "Content-Type: application/json" \
+  -X POST \
   --data '{"username":"abc","password":"def"}'
    @@ -387,6 +714,10 @@ }

    This endpoint is used to authenticate and retrieve a JWT token.

    + +

    HTTP Request

    POST https://goscrobble.com/api/v1/login

    Query Parameters

    @@ -408,12 +739,13 @@ Account password -

    v1/register

    +

    POST v1/register

    Create a new account (Replace default credentials):

    curl "https://goscrobble.com/api/v1/register" \
   -H "Content-Type: application/json" \
+  -X POST \
   --data '{"email": "test@test.com", "username":"abc","password":"def"}'
    @@ -424,6 +756,10 @@ }

    If the server has REGISTRATION_ENABLED=true set, this endpoint will allow you to create a new account. Password must be at least 8 characters long.

    + +

    HTTP Request

    POST https://goscrobble.com/api/v1/register

    Query Parameters

    @@ -450,12 +786,13 @@ Account password -

    v1/sendreset

    +

    POST v1/sendreset

    Trigger a password reset email:

    curl "https://goscrobble.com/api/v1/sendreset" \
   -H "Content-Type: application/json" \
+  -X POST \
   --data '{"email":"test@test.com"}'
    @@ -466,6 +803,10 @@ }

    This endpoint triggers a password reset email to be sent to the email on an account.

    + +

    HTTP Request

    POST https://goscrobble.com/api/v1/sendreset

    Query Parameters

    @@ -482,12 +823,13 @@ Account username -

    v1/resetpassword

    +

    POST v1/resetpassword

    Trigger a password reset email:

    curl "https://goscrobble.com/api/v1/resetpassword" \
   -H "Content-Type: application/json" \
+  -X POST \
   --data '{"token":"abcdefghijklmnopqrstuvwxyz", "password": "Hunter1"}'
    @@ -498,6 +840,10 @@ }

    This endpoint confirms a password reset with a valid hash from the reset email. You must call v1/sendreset first and obtain the hash.

    + +

    HTTP Request

    POST https://goscrobble.com/api/v1/resetpassword

    Query Parameters

    @@ -518,6 +864,108 @@ true New account password + +

    POST v1/refresh

    +
    +

    Fetch a new JWT with a refresh token:

    +
    +
    curl "https://goscrobble.com/api/v1/refresh" \
+  -H "Content-Type: application/json" \
+  -X POST \
+  --data '{"token":"abcdefghijklmnopqrstuvwxyz"}'
+
    +
    +

    Response:

    +
    +
    {
+  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsInJlZnJlc2hfZXhwIjoxNjQxMDAyNTE5LCJyZWZyZXNoX3Rva2VuIjoiYWJjZGVmZ2hqaWtsbW5vcHF3ZXJ0dXZ3eHl6Iiwic3ViIjoiNDE4ZmRkZmItOGIxYi01MWFiLTliZHMtNGZnMDhjYTYzY2ZmIiwidXNlcm5hbWUiOiJ0ZXN0In0.fuPXjQ7IzNyttgIKpdS4-KBQ-QeHTl-BfgYkSnMCmpVrBunzMrSwr1RzxI7Xg2WWF-FHtW3Bnv9RpSqLDN4F2g"
+}
+
    +

    Returns a new JWT token by passing a refresh token.

    + + +

    HTTP Request

    +

    POST https://goscrobble.com/api/v1/refresh

    +

    Query Parameters

    + + + + + + + + + + + + +
    ParameterRequiredDescription
    tokentrueRefresh token from previously issued JWT
    +

    Admin Endpoints

    + +

    GET v1/config

    +
    +

    Fetch configuration values:

    +
    +
    curl "https://goscrobble.com/api/v1/config" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI"
+
    +
    +

    Response:

    +
    +
    {
+  "SPOTIFY_API_ID": "abc",
+  "SPOTIFY_API_SECRET": "def",
+  "REGISTRATION_ENABLED": true
+}
+
    +

    Fetch instance configuration values.

    + + +

    HTTP Request

    +

    GET https://goscrobble.com/api/v1/config

    +

    POST v1/config

    +
    +

    Update a configuration parameter:

    +
    +
    curl "https://goscrobble.com/api/v1/config" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \
+  -X POST \
+  --data '{"SPOTIFY_API_ID":"notarealapikey","SPOTIFY_API_SECRET":"notarealsecret"}'
+
    +
    +

    Response:

    +
    +
    {
+  "message": "Config updated successfully"
+}
+
    +

    Updates instance configuration values.

    + + +

    HTTP Request

    +

    POST https://goscrobble.com/api/v1/config

    +

    Query Parameters

    + + + + + + + + + + + +
    ParameterRequiredDescription
    keytrueArray of key/value pairs to update. See example.
    diff --git a/docs/api/source/includes/_admin.md b/docs/api/source/includes/_admin.md new file mode 100644 index 00000000..f393328b --- /dev/null +++ b/docs/api/source/includes/_admin.md @@ -0,0 +1,70 @@ +# Admin Endpoints + + +## GET v1/config + +> Fetch configuration values: + +```shell +curl "https://goscrobble.com/api/v1/config" \ + -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" +``` + +> Response: + +```json +{ + "SPOTIFY_API_ID": "abc", + "SPOTIFY_API_SECRET": "def", + "REGISTRATION_ENABLED": true +} +``` + +Fetch instance configuration values. + + + +### HTTP Request + +`GET https://goscrobble.com/api/v1/config` + + +## POST v1/config + +> Update a configuration parameter: + +```shell +curl "https://goscrobble.com/api/v1/config" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \ + -X POST \ + --data '{"SPOTIFY_API_ID":"notarealapikey","SPOTIFY_API_SECRET":"notarealsecret"}' +``` + +> Response: + +```json +{ + "message": "Config updated successfully" +} +``` + +Updates instance configuration values. + + + +### HTTP Request + +`POST https://goscrobble.com/api/v1/config` + +### Query Parameters + +Parameter | Required | Description +--------- | ------- | ----------- +key | true | Array of key/value pairs to update. See example. \ No newline at end of file diff --git a/docs/api/source/includes/_authentication.md b/docs/api/source/includes/_authentication.md index c74bd382..95ff0ac9 100644 --- a/docs/api/source/includes/_authentication.md +++ b/docs/api/source/includes/_authentication.md @@ -1,12 +1,13 @@ # Authentication -## v1/login +## POST v1/login > To obtain a JWT token (Replace default credentials): ```shell curl "https://goscrobble.com/api/v1/login" \ -H "Content-Type: application/json" \ + -X POST \ --data '{"username":"abc","password":"def"}' ``` @@ -20,6 +21,10 @@ curl "https://goscrobble.com/api/v1/login" \ This endpoint is used to authenticate and retrieve a JWT token. + + ### HTTP Request `POST https://goscrobble.com/api/v1/login` @@ -31,13 +36,14 @@ Parameter | Required | Description username | true | Account username password | true | Account password -## v1/register +## POST v1/register > Create a new account (Replace default credentials): ```shell curl "https://goscrobble.com/api/v1/register" \ -H "Content-Type: application/json" \ + -X POST \ --data '{"email": "test@test.com", "username":"abc","password":"def"}' ``` @@ -51,6 +57,10 @@ curl "https://goscrobble.com/api/v1/register" \ If the server has REGISTRATION_ENABLED=true set, this endpoint will allow you to create a new account. Password must be at least 8 characters long. + + ### HTTP Request `POST https://goscrobble.com/api/v1/register` @@ -63,13 +73,14 @@ email | true | Account email username | true | Account username password | true | Account password -## v1/sendreset +## POST v1/sendreset > Trigger a password reset email: ```shell curl "https://goscrobble.com/api/v1/sendreset" \ -H "Content-Type: application/json" \ + -X POST \ --data '{"email":"test@test.com"}' ``` @@ -83,6 +94,10 @@ curl "https://goscrobble.com/api/v1/sendreset" \ This endpoint triggers a password reset email to be sent to the email on an account. + + ### HTTP Request `POST https://goscrobble.com/api/v1/sendreset` @@ -93,13 +108,14 @@ Parameter | Required | Description --------- | ------- | ----------- email | true | Account username -## v1/resetpassword +## POST v1/resetpassword > Trigger a password reset email: ```shell curl "https://goscrobble.com/api/v1/resetpassword" \ -H "Content-Type: application/json" \ + -X POST \ --data '{"token":"abcdefghijklmnopqrstuvwxyz", "password": "Hunter1"}' ``` @@ -113,6 +129,10 @@ curl "https://goscrobble.com/api/v1/resetpassword" \ This endpoint confirms a password reset with a valid hash from the reset email. You must call v1/sendreset first and obtain the hash. + + ### HTTP Request `POST https://goscrobble.com/api/v1/resetpassword` @@ -124,3 +144,37 @@ Parameter | Required | Description token | true | Reset token from the password reset email password | true | New account password +## POST v1/refresh + +> Fetch a new JWT with a refresh token: + +```shell +curl "https://goscrobble.com/api/v1/refresh" \ + -H "Content-Type: application/json" \ + -X POST \ + --data '{"token":"abcdefghijklmnopqrstuvwxyz"}' +``` + +> Response: + +```json +{ + "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsInJlZnJlc2hfZXhwIjoxNjQxMDAyNTE5LCJyZWZyZXNoX3Rva2VuIjoiYWJjZGVmZ2hqaWtsbW5vcHF3ZXJ0dXZ3eHl6Iiwic3ViIjoiNDE4ZmRkZmItOGIxYi01MWFiLTliZHMtNGZnMDhjYTYzY2ZmIiwidXNlcm5hbWUiOiJ0ZXN0In0.fuPXjQ7IzNyttgIKpdS4-KBQ-QeHTl-BfgYkSnMCmpVrBunzMrSwr1RzxI7Xg2WWF-FHtW3Bnv9RpSqLDN4F2g" +} +``` + +Returns a new JWT token by passing a refresh token. + + + +### HTTP Request + +`POST https://goscrobble.com/api/v1/refresh` + +### Query Parameters + +Parameter | Required | Description +--------- | ------- | ----------- +token | true | Refresh token from previously issued JWT diff --git a/docs/api/source/includes/_errors.md b/docs/api/source/includes/_errors.md deleted file mode 100644 index 7b35e92b..00000000 --- a/docs/api/source/includes/_errors.md +++ /dev/null @@ -1,22 +0,0 @@ -# Errors - - - -The Kittn API uses the following error codes: - - -Error Code | Meaning ----------- | ------- -400 | Bad Request -- Your request is invalid. -401 | Unauthorized -- Your API key is wrong. -403 | Forbidden -- The kitten requested is hidden for administrators only. -404 | Not Found -- The specified kitten could not be found. -405 | Method Not Allowed -- You tried to access a kitten with an invalid method. -406 | Not Acceptable -- You requested a format that isn't json. -410 | Gone -- The kitten requested has been removed from our servers. -418 | I'm a teapot. -429 | Too Many Requests -- You're requesting too many kittens! Slow down! -500 | Internal Server Error -- We had a problem with our server. Try again later. -503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. diff --git a/docs/api/source/includes/_ingress.md b/docs/api/source/includes/_ingress.md new file mode 100644 index 00000000..31f80120 --- /dev/null +++ b/docs/api/source/includes/_ingress.md @@ -0,0 +1,109 @@ +# Ingress Endpoints + +Spotify and Navidrome both work on a poll based system and do not require incoming webhooks/endpoints. + +## POST v1/ingress/jellyfin + +> Submit a scrobble: + +```shell +curl "https://goscrobble.com/api/v1/ingress/jellyfin" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \ + -X POST \ + --data '{"Name":"", "Album":"Best Album","Artist":"Best Artist"}' +``` + +> Response: + +```json +{ + "message": "success" +} +``` + +Adds a scrobble from Jellyfin into the database. Please view `type JellyfinRequest struct` in ingress_jellyfin.go for the full request format. You need to install the webhook plugin for this to work. + + + +### HTTP Request + +`POST https://goscrobble.com/api/v1/ingress/jellyfin` + +### Query Parameters + +Parameter | Required | Type | Description +--------- | ------- | ----------- | ----------- +Album | true | string | Album title +Artist | true | string | Artist name +Name | true | string | Song title +ItemType | true | string | Will only scrobble type 'Audio' +ClientName | false | string | TBD +DeviceId | false | string | TBD +DeviceName | false | string | TBD +IsAutomated | false | bool | TBD +IsPaused | false | bool | TBD +ItemId | false | string | TBD +MediaSourceId | false | string | TBD +NotificationType | false | string | TBD +Overview | false | string | TBD +PlaybackPosition | false | string | TBD +PlaybackPositionTicks | false | int | TBD +Provider_musicbrainzalbum | false | string | TBD +Provider_musicbrainzalbumartist | false | string | TBD +Provider_musicbrainzartist | false | string | TBD +Provider_musicbrainzreleasegroup | false | string | TBD +Provider_musicbrainztrack | false | string | TBD +RunTime | false | string | TBD +RunTimeTicks | false | int | TBD +ServerId | false | string | TBD +ServerName | false | string | TBD +ServerUrl | false | string | TBD +ServerVersion | false | string | TBD +Timestamp | false | string | TBD +UserId | false | TBD +Username | false | TBD +UtcTimestamp | false | TBD +Year | false | int | TBD + +## POST v1/ingress/multiscrobbler + +> Submit a scrobble: + +```shell +curl "https://goscrobble.com/api/v1/ingress/multiscrobbler" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \ + -X POST \ + --data '{"Track":"", "Album":"Best Album","Artist":["Best Artist1", "Best Artist2"]}' +``` + +> Response: + +```json +{ + "message": "success" +} +``` + +Adds a scrobble from MultiScrobbler into the database. Please view `type MultiScrobblerRequest struct` in ingress_multiscrobbler.go for the full request format. + + + +### HTTP Request + +`POST https://goscrobble.com/api/v1/ingress/multiscrobbler` + +### Query Parameters + +Parameter | Required | Type | Description +--------- | ------- | ----------- | ----------- +Album | true | string | Album title +Artist | true | array | Array of Artist names +Track | true | string | Song title +PlayedAt | true | int | Unix Timestamp of scrobble time +Duration | true | int | Song length in seconds \ No newline at end of file diff --git a/docs/api/source/includes/_introduction.md b/docs/api/source/includes/_introduction.md index 19b4193f..9fbfa96e 100644 --- a/docs/api/source/includes/_introduction.md +++ b/docs/api/source/includes/_introduction.md @@ -2,4 +2,4 @@ Welcome to the GoScrobble API documentation. -The majority of these API endpoints are public with reasonable rate limits. \ No newline at end of file +The majority of these API endpoints are public with rate limiting and do not require authentication. \ No newline at end of file diff --git a/docs/api/source/includes/_ratelimits.md b/docs/api/source/includes/_ratelimits.md new file mode 100644 index 00000000..0b068a57 --- /dev/null +++ b/docs/api/source/includes/_ratelimits.md @@ -0,0 +1,13 @@ +# Rate Limits + +There are 3 tiers of rate-limiting: +Light rate-limiting: 1 request per 4 seconds with a max burst of 2. +Standard rate-limiting: 5 requests per second with a burst of 5. +Heavy rate-limiting: 10 requests per second with a burst of 10. + +The rate limits work as a 'bucket' system where there is a max (burst) and a regenerative rate. More info can be found in the source file server_middleware.go. + +Each endpoint will depict which rate limit applies. + +For example: +On the medium rate-limiter, you start with 5 requests available to you instantly, and this replenishes 5 requests per second. diff --git a/docs/api/source/includes/_serverinfo.md b/docs/api/source/includes/_serverinfo.md index ede2c636..631afd65 100644 --- a/docs/api/source/includes/_serverinfo.md +++ b/docs/api/source/includes/_serverinfo.md @@ -1,5 +1,5 @@ # Server Info -## v1/serverinfo +## GET v1/serverinfo > Check server version and registration status: ```shell diff --git a/docs/api/source/index.html.md b/docs/api/source/index.html.md index daf59bd0..b558cc8e 100644 --- a/docs/api/source/index.html.md +++ b/docs/api/source/index.html.md @@ -11,8 +11,11 @@ toc_footers: includes: - introduction + - ratelimits - serverinfo + - ingress - authentication + - admin search: true