refine api docs, new apis added

docs/API.md

@@ -4,43 +4,67 @@ Just go to `/_/info` endpoint
 
 # API
 
-To make use of it, instance must have API enabled of course. Currently, there is only one functionality present. If you are working on some cool project and wanna have more functionality here, let me know
+To make use of it, instance must have API enabled of course. All responses are in JSON format if the request is successful. Errors are just returned as plaintext. Currently, there is few functionality present. If you are working on some cool project and wanna have more functionality here, let me know
 
-## Searching
+## Paginated endpoints
 
-You can search with endpoint `/_/api/search`. Query parameters are:
+Those endpoints return an object with properties:
+- `collection`: List of the results on this page
+- `total_results`: total results duh, maybe 0 on some endpoints
+- `next_href`: Link to next page
+
+To go to next page, take the `next_href`, strip away everything until `?`, and pass that as `pagination` query parameter. Note that not all endpoints may support going to next page.
+
+You can also use `pagination` parameter to pass raw arguments into soundcloud api (for example, more advanced search filters, different initial result limit, etc)
+
+## GET `/_/api/search`
+
+Search for users, tracks or playlists. Query parameters are:
 - `q`: the query
 - `type`: `users`, `tracks`, or `playlists`. Required
-- `pagination`: raw parameters to pass into soundcloud's api
+- `pagination`: [Read above](#paginated-endpoints)
-
-The response is in JSON format. To go to next page, take the `next_href` from result, strip away everything until `?`, and pass that as `pagination` parameter.
 
 For example: `/_/api/search?q=test&type=tracks` to search for `tracks` named `test`
 
+## GET `/_/api/track/:id/related`
+
+Get related tracks by ID. Pagination is supported here. Initial request returns upto 20 tracks
+
+For example: `/_/api/track/2014143543/related` to get tracks related to track with ID `2014143543`
+
+## GET `/_/api/tracks`
+
+Get tracks by ID in bulk. Pass the IDs comma-separated as `ids` query parameter. You can't request more than 50 tracks at once. The result is a list, which only contains the tracks which were successfully resolved
+
+For example: `/_/api/tracks?ids=2014143543,476907846`. This will only return one track, since 2nd ID is not a track ID
+
+## GET `/_/api/playlistByPermalink/:author/sets/:playlist`
+
+Get playlist by permalinks. 
+
+For example: `/_/api/playlistByPermalink/lucybedroque/sets/unmusique` to get `unmusique` playlist from `lucybedroque`
+
 # Other automation
 
 Doesn't require API to be enabled
 
-## Download songs
+## GET `/_/restream/:author/:track`
 
-Restream must be enabled in the instance. The endpoint is `/_/restream/<author permalink>/<track permalink>`. Query parameters are:
+Restream must be enabled in the instance. This endpoint can be used to download or stream tracks. Query parameters are:
 - `metadata`: `true` or `false`. If `true`, soundcloak will inject metadata (author, track cover, track title, etc) into the audio file, but this may take a little bit more time
 - `audio`: `best`, `aac`, `opus`, or `mpeg`. [Read more here](AUDIO_PRESETS.md)
 
+Restream converts the HLS playlist to an audio file on the fly serverside, optionally adding metadata. Please note that when `audio` is `opus` and `metadata` is `true`, it's not done on the fly, as metadata injection is a bit tricky there.
+
 For example: `/_/restream/lucybedroque/speakers?metadata=true&audio=opus` to get the `opus` audio with `metadata` for song `speakers` by author `lucybedroque`
 
-## Get search suggestions
+## GET `/_/searchSuggestions`
 
-The endpoint is `/_/searchSuggestions`. Query parameters are:
+Pass your query as `q` query parameter
-- `q`: the query
-
-The response is a list of search suggestions as strings in JSON format.
 
 For example: `/_/searchSuggestions?q=hi` to get search suggestions for `hi`
 
-## Proxy images
+## GET `/_/proxy/images`
 
-ProxyImages must be enabled in the instance. 
+ProxyImages must be enabled in the instance. Put image url into `url` query parameter. Of course, this only proxies images from soundcloud cdn
-
-Endpoint for images: `/_/proxy/images`. Put image url into `url` query parameter. Of course, this only proxies images from soundcloud cdn
 

go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/gcottom/oggmeta v0.0.8
 	github.com/goccy/go-json v0.10.5
 	github.com/gofiber/fiber/v3 v3.0.0-beta.4
-	github.com/valyala/fasthttp v1.62.0
+	github.com/valyala/fasthttp v1.63.0
 )
 
 require (

go.sum

@@ -62,8 +62,8 @@ github.com/tinylib/msgp v1.3.0 h1:ULuf7GPooDaIlbyvgAxBV/FI7ynli6LZ1/nVUNu+0ww=
 github.com/tinylib/msgp v1.3.0/go.mod h1:ykjzy2wzgrlvpDCRc4LA8UXy6D8bzMSuAF3WD57Gok0=
 github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
 github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
-github.com/valyala/fasthttp v1.62.0 h1:8dKRBX/y2rCzyc6903Zu1+3qN0H/d2MsxPPmVNamiH0=
+github.com/valyala/fasthttp v1.63.0 h1:DisIL8OjB7ul2d7cBaMRcKTQDYnrGy56R4FCiuDP0Ns=
-github.com/valyala/fasthttp v1.62.0/go.mod h1:FCINgr4GKdKqV8Q0xv8b+UxPV+H/O5nNFo3D+r54Htg=
+github.com/valyala/fasthttp v1.63.0/go.mod h1:REc4IeW+cAEyLrRPa5A81MIjvz0QE1laoTX2EaPHKJM=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
 github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=

lib/api/init.go

@@ -5,18 +5,16 @@ import (
 	"net/url"
 
 	"git.maid.zone/stuff/soundcloak/lib/cfg"
-	"git.maid.zone/stuff/soundcloak/lib/preferences"
 	"git.maid.zone/stuff/soundcloak/lib/sc"
 	"github.com/gofiber/fiber/v3"
+	json "github.com/goccy/go-json"
 )
 
-func Load(r *fiber.App) {
+func Load(a *fiber.App) {
-	r.Get("/_/api/search", func(c fiber.Ctx) error {
+	r := a.Group("/_/api")
-		prefs, err := preferences.Get(c)
+	
-		if err != nil {
+	prefs := cfg.Preferences{ProxyImages: &cfg.False}
-			return err
+	r.Get("/search", func(c fiber.Ctx) error {
-		}
-
 		q := cfg.B2s(c.RequestCtx().QueryArgs().Peek("q"))
 		t := cfg.B2s(c.RequestCtx().QueryArgs().Peek("type"))
 		args := cfg.B2s(c.RequestCtx().QueryArgs().Peek("pagination"))
@@ -55,4 +53,40 @@ func Load(r *fiber.App) {
 
 		return c.SendStatus(404)
 	})
+
+	r.Get("/track/:id/related", func(c fiber.Ctx) error {
+		args := cfg.B2s(c.RequestCtx().QueryArgs().Peek("pagination"))
+		if args == "" {
+			args = "?limit=20"
+		}
+
+		p, err := (sc.Track{ID: json.Number(c.Params("id"))}).GetRelated("", prefs, args)
+		if err != nil {
+			log.Printf("[API] error getting related tracks for %d: %s\n", c.Params("id"), err)
+			return err
+		}
+
+		return c.JSON(p)
+	})
+
+	r.Get("/playlistByPermalink/:author/sets/:playlist", func(c fiber.Ctx) error {
+		p, err := sc.GetPlaylist("", c.Params("author")+"/sets/"+c.Params("playlist"))
+		if err != nil {
+			log.Printf("[API] error getting %s playlist from %s: %s\n", c.Params("playlist"), c.Params("author"), err)
+			return err
+		}
+
+		return c.JSON(p)
+	})
+
+	r.Get("/tracks", func(c fiber.Ctx) error {
+		ids := cfg.B2s(c.RequestCtx().QueryArgs().Peek("ids"))
+		t, err := sc.GetTracks("", ids)
+		if err != nil {
+			log.Printf("[API] error getting %s tracks: %s\n", ids, err)
+			return err
+		}
+
+		return c.JSON(t)
+	})
 }

lib/sc/user.go

@@ -37,7 +37,7 @@ type User struct {
 	Verified     bool        `json:"verified"`
 	Station      string      `json:"station_permalink"`
 
-	WebProfiles []Link
+	WebProfiles []Link `json:",omitempty"`
 }
 
 type Link struct {