mirror of
https://github.com/idanoo/GoScrobble
synced 2025-07-02 22:22:19 +00:00
Update API docs
This commit is contained in:
parent
306bab997b
commit
c860b4e2b7
9 changed files with 714 additions and 39 deletions
70
docs/api/source/includes/_admin.md
Normal file
70
docs/api/source/includes/_admin.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# Admin Endpoints
|
||||
<aside class="warning">
|
||||
An admin JWT token is required for the below endpoints
|
||||
</aside>
|
||||
|
||||
## 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.
|
||||
|
||||
<aside class="notice">
|
||||
Standard rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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.
|
||||
|
||||
<aside class="notice">
|
||||
Standard rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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.
|
||||
|
|
@ -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.
|
||||
|
||||
<aside class="notice">
|
||||
Standard rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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.
|
||||
|
||||
<aside class="notice">
|
||||
Heavy rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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.
|
||||
|
||||
<aside class="notice">
|
||||
Heavy rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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.
|
||||
|
||||
<aside class="notice">
|
||||
Heavy rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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.
|
||||
|
||||
<aside class="notice">
|
||||
Standard rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### HTTP Request
|
||||
|
||||
`POST https://goscrobble.com/api/v1/refresh`
|
||||
|
||||
### Query Parameters
|
||||
|
||||
Parameter | Required | Description
|
||||
--------- | ------- | -----------
|
||||
token | true | Refresh token from previously issued JWT
|
||||
|
|
|
|||
|
|
@ -1,22 +0,0 @@
|
|||
# Errors
|
||||
|
||||
<aside class="notice">
|
||||
This error section is stored in a separate file in <code>includes/_errors.md</code>. Slate allows you to optionally separate out your docs into many files...just save them to the <code>includes</code> folder and add them to the top of your <code>index.md</code>'s frontmatter. Files are included in the order listed.
|
||||
</aside>
|
||||
|
||||
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.
|
||||
109
docs/api/source/includes/_ingress.md
Normal file
109
docs/api/source/includes/_ingress.md
Normal file
|
|
@ -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":"<Full JSON structure located in ingress_jellyfin.go>", "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.
|
||||
|
||||
<aside class="notice">
|
||||
Light rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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":"<Full JSON structure located in ingress_multiscrobbler.go>", "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.
|
||||
|
||||
<aside class="notice">
|
||||
Light rate-limiting applies
|
||||
</aside>
|
||||
|
||||
### 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
|
||||
|
|
@ -2,4 +2,4 @@
|
|||
|
||||
Welcome to the GoScrobble API documentation.
|
||||
|
||||
The majority of these API endpoints are public with reasonable rate limits.
|
||||
The majority of these API endpoints are public with rate limiting and do not require authentication.
|
||||
13
docs/api/source/includes/_ratelimits.md
Normal file
13
docs/api/source/includes/_ratelimits.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
# Server Info
|
||||
## v1/serverinfo
|
||||
## GET v1/serverinfo
|
||||
> Check server version and registration status:
|
||||
|
||||
```shell
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue