From 97a6087e424859208dd45162193138499f6c4150 Mon Sep 17 00:00:00 2001 From: Daniel Mason Date: Sat, 25 Dec 2021 20:58:24 +1300 Subject: [PATCH] Update API Docs --- README.md | 8 +- docs/api/build/index.html | 554 +++++++++++----------- docs/api/source/includes/_admin.md | 2 +- docs/api/source/includes/_introduction.md | 4 +- docs/api/source/index.html.md | 5 +- 5 files changed, 285 insertions(+), 288 deletions(-) diff --git a/README.md b/README.md index f343fb19..462a03a0 100644 --- a/README.md +++ b/README.md @@ -22,18 +22,12 @@ Copy .env.example to .env and set variables. You can use https://www.grc.com/pas cp .env.example .env # Fill in the blanks go mod tidy CGO_ENABLED=0 go run cmd/go-scrobble/*.go - # In another terminal cp web/.env.example web/.env.development and set vars - cd web && npm install && npm start --env development -Access dev frontend @ http://127.0.0.1:3000 + API @ http://127.0.0.1:42069/api/v1 +Access API @ http://127.0.0.1:42069/api/v1 ## Prod deployment -We need to build NPM package, and then ship web/build with the binary. - cp .env.example .env # Fill in the blanks - cp web/.env.example web/.env.production - cd web npm install --production && npm run build --env production go build -o goscrobble cmd/go-scrobble/*.go ./goscrobble diff --git a/docs/api/build/index.html b/docs/api/build/index.html index 1caefa2c..36a5e6ae 100644 --- a/docs/api/build/index.html +++ b/docs/api/build/index.html @@ -327,13 +327,13 @@
  • - Ingress Endpoints + Administration
    • @@ -358,13 +358,13 @@
  • - Admin Endpoints + Ingress Endpoints
    • @@ -382,6 +382,8 @@

    Welcome to the GoScrobble API documentation.

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

    + +

    Base URL for the API endpoints: https://goscrobble.com/api

    Rate Limits

    There are 3 tiers of rate-limiting:
    Light rate-limiting: 1 request per 4 seconds with a max burst of 2.
    @@ -411,6 +413,276 @@ On the medium rate-limiter, you start with 5 requests available to you instantly

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

    HTTP Request

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

    +

    Administration

    + +

    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.
    +

    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"}'
+
    +
    +

    Response:

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

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

    + + +

    HTTP Request

    +

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

    +

    Query Parameters

    + + + + + + + + + + + + + + + + + +
    ParameterRequiredDescription
    usernametrueAccount username
    passwordtrueAccount password
    +

    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"}'
+
    +
    +

    Response:

    +
    +
    {
+  "message": "User created succesfully. You may now login"
+}
+
    +

    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

    + + + + + + + + + + + + + + + + + + + + + + +
    ParameterRequiredDescription
    emailtrueAccount email
    usernametrueAccount username
    passwordtrueAccount password
    +

    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"}'
+
    +
    +

    Response:

    +
    +
    {
+  "message": "Password reset email sent"
+}
+
    +

    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

    + + + + + + + + + + + + +
    ParameterRequiredDescription
    emailtrueAccount username
    +

    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"}'
+
    +
    +

    Response:

    +
    +
    {
+  "message": "Password updated successfully!"
+}
+
    +

    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

    + + + + + + + + + + + + + + + + + +
    ParameterRequiredDescription
    tokentrueReset token from the password reset email
    passwordtrueNew 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

    Ingress Endpoints

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

    POST v1/ingress/jellyfin

    @@ -696,276 +968,6 @@ Light rate-limiting applies int Song 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"}'
-
    -
    -

    Response:

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

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

    - - -

    HTTP Request

    -

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

    -

    Query Parameters

    - - - - - - - - - - - - - - - - - -
    ParameterRequiredDescription
    usernametrueAccount username
    passwordtrueAccount password
    -

    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"}'
-
    -
    -

    Response:

    -
    -
    {
-  "message": "User created succesfully. You may now login"
-}
-
    -

    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

    - - - - - - - - - - - - - - - - - - - - - - -
    ParameterRequiredDescription
    emailtrueAccount email
    usernametrueAccount username
    passwordtrueAccount password
    -

    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"}'
-
    -
    -

    Response:

    -
    -
    {
-  "message": "Password reset email sent"
-}
-
    -

    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

    - - - - - - - - - - - - -
    ParameterRequiredDescription
    emailtrueAccount username
    -

    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"}'
-
    -
    -

    Response:

    -
    -
    {
-  "message": "Password updated successfully!"
-}
-
    -

    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

    - - - - - - - - - - - - - - - - - -
    ParameterRequiredDescription
    tokentrueReset token from the password reset email
    passwordtrueNew 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 index f393328b..cfa14ecf 100644 --- a/docs/api/source/includes/_admin.md +++ b/docs/api/source/includes/_admin.md @@ -1,4 +1,4 @@ -# Admin Endpoints +# Administration diff --git a/docs/api/source/includes/_introduction.md b/docs/api/source/includes/_introduction.md index 9fbfa96e..7f8f706e 100644 --- a/docs/api/source/includes/_introduction.md +++ b/docs/api/source/includes/_introduction.md @@ -2,4 +2,6 @@ Welcome to the GoScrobble API documentation. -The majority of these API endpoints are public with rate limiting and do not require authentication. \ No newline at end of file +The majority of these API endpoints are public with rate limiting and do not require authentication. + +Base URL for the API endpoints: https://goscrobble.com/api diff --git a/docs/api/source/index.html.md b/docs/api/source/index.html.md index b558cc8e..c6ce3972 100644 --- a/docs/api/source/index.html.md +++ b/docs/api/source/index.html.md @@ -13,9 +13,9 @@ includes: - introduction - ratelimits - serverinfo - - ingress - - authentication - admin + - authentication + - ingress search: true @@ -25,4 +25,3 @@ meta: - name: description content: Documentation for the GoScrobble API --- -