github.com/derat/nup@v0.0.0-20230418113745-15592ba7c620/server/README.md (about) 1 # nup Google App Engine server 2 3 ## HTTP endpoints 4 5 ### / (GET) 6 7 Returns the index page. 8 9 ### /clear (POST, dev-only) 10 11 Deletes all song and play objects from Datastore. Used by tests. 12 13 ### /config (POST, dev-only) 14 15 Modifies server behavior. Used by tests. 16 17 * `forceUpdateFailures` (optional) - If `1`, report failures for all user data 18 updates (ratings, tags, plays). 19 20 ### /cover (GET) 21 22 Returns an album cover art image in JPEG format. 23 24 * `filename` - Image path from [Song]'s `CoverFilename` field. 25 * `size` (optional) - Integer cover dimensions, e.g. `400` to request that the 26 image be scaled (and possibly cropped) to 400x400. 27 * `webp` (optional) - If `1`, return a prescaled WebP version of the image if 28 available. If unavailable, return JPEG. 29 30 ### /delete\_song (POST) 31 32 Deletes a song from Datastore. 33 34 * `songId` - Integer ID from [Song]'s `SongID` field. 35 36 ### /dump\_song (GET) 37 38 Returns a JSON-marshaled [Song] object. [Play]s are included. 39 40 * `songId` - Integer ID from [Song]'s `SongID` field. 41 42 ### /export (GET) 43 44 Returns a series of JSON-marshaled [Song] or [Play] objects, followed by an 45 optional JSON string containing a cursor for the next batch if not all objects 46 were returned. 47 48 * `cursor` (optional) - Cursor to continue an earlier request. 49 * `max` (optional) - Integer maximum number of items to return. 50 * `type` - Type of entity to export (`song` or `play`). 51 52 Several parameters are only relevant for the `song` type: 53 54 * `deleted` (optional) - If `1`, return deleted songs rather than non-deleted 55 songs. 56 * `minLastModifiedNsec` (optional) - Integer nanoseconds since Unix epoch of 57 songs' last-modified timestamps. Used for incremental updates. 58 * `omit` (optional) - Comma-separated list of [Song] fields to clear. 59 Available fields are `coverFilename`, `plays`, and `sha1`. 60 61 ### /flush\_cache (POST, dev-only) 62 63 Flushes data cached in Memcache (and possibly also in Datastore). Used by tests. 64 65 * `onlyMemcache` (optional) - If `1`, don't flush the Datastore cache. 66 67 ### /import (POST) 68 69 Imports a series (not an array) of JSON-marshaled [Song] and [Play] objects 70 into Datastore. 71 72 * `replaceUserData` (optional) - If `1`, replace the songs' existing user data 73 in Datastore (ratings, tags, play history) with user data from the supplied 74 songs. Otherwise, the existing data is preserved. 75 * `updateDelayNsec` (optional) - Integer value containing nanoseconds to wait 76 before writing to Datastore. Used by tests. 77 * `useFilenames` (optional) - If `1`, identify songs by filenames rather than 78 hashes of their audio data. This is useful after updating a file's data 79 (e.g. to correct errors): as long as its path renames the same, the existing 80 entity will be updated rather than a new one being inserted. 81 82 ### /now (GET) 83 84 Returns the server's current time as integer nanoseconds since the Unix epoch. 85 86 ### /played (POST) 87 88 Records a single play of a song in Datastore. Also saves the reporter's IP 89 address. 90 91 * `songId` - Integer ID from [Song]'s `SongID` field. 92 * `startTime` - RFC 3339 string specifying when playback of the song started. 93 Float seconds since the Unix epoch are also accepted. 94 95 ### /presets (GET) 96 97 Returns a JSON-marshaled array of [SearchPreset] objects describing search 98 presets that can be used by clients. If the server's configuration specified 99 custom presets for the requesting user, they are returned instead of the default 100 presets. 101 102 ### /query (GET) 103 104 Queries Datastore and returns a JSON-marshaled array of [Song]s. 105 106 * `album` (optional) - String album name. 107 * `albumId` (optional) - String album ID from `MusicBrainz Album Id` field, 108 e.g. `124f4108-fec8-4663-b69c-19b37ff1703c`. 109 * `artist` (optional) - String artist name. 110 * `cacheOnly` (optional) - If `1`, only return cached data. Used by tests. 111 * `keywords` (optional) - Space-separated keywords to match against artists, 112 titles, and albums. 113 * `fallback` (optional) - If `force`, only uses the fallback mode that tries 114 to avoid using composite indexes in Datastore. If `never`, doesn't use the 115 fallback mode at all. Used by tests. 116 * `filename` (optional) - String song filename relative to music directory. 117 * `firstTrack` (optional) - If `1`, only returns songs that are the first 118 tracks of first discs. 119 * `maxDate` (optional) - RFC 3339 string containing maximum song date. 120 * `maxLastPlayed` (optional) - RFC 3339 string specifying the maximum time at 121 which songs were last played (to select music that hasn't been played 122 recently). Float seconds since the Unix epoch are also accepted. 123 * `maxPlays` (optional) - Integer maximum number of plays. 124 * `maxRating` (optional) - Integer maximum song rating in the range `[1, 5]`. 125 Unrated songs are not returned when this parameter is supplied. 126 * `minDate` (optional) - RFC 3339 string containing minimum song date. 127 * `minFirstPlayed` (optional) - RFC 3339 string specifying the minimum time at 128 which songs were first played (to select recently-added music). Float 129 seconds since the Unix epoch are also accepted. 130 * `minRating` (optional) - Integer minimum song rating in the range `[1, 5]`. 131 * `orderByLastPlayed` (optional) - If `1`, return songs that were last played 132 the longest ago. 133 * `rating` (optional) - Integer song rating in the range `[1, 5]`. 134 * `shuffle` (optional) - If `1`, shuffle the order of returned songs. 135 * `unrated` (optional) - If `1`, return only songs that have no rating. 136 * `tags` (optional) - Space-separated tags, e.g. `electronic -vocals`. Tags 137 preceded by `-` must not be present. All other tags must be present. 138 * `title` (optional) - String song title. 139 140 ### /rate\_and\_tag (POST) 141 142 Updates a song's rating and/or tags in Datastore. 143 144 * `rating` (optional) - Integer rating for the song in the range `[1, 5]`, 145 or `0` to clear the song's rating. See [Song]'s `Rating` field. 146 * `songId` - Integer ID from [Song]'s `SongID` field. 147 * `tags` (optional) - Space-separated tags for the song. See [Song]'s `Tags` 148 field. 149 * `updateDelayNsec` (optional) - Integer value containing nanoseconds to wait 150 before writing to Datastore. Used by tests. 151 152 ### /reindex (POST) 153 154 Regenerates fields used for searching across all [Song] objects. Returns a JSON 155 object containing `scanned` and `updated` number properties and a `cursor` 156 string property. If the returned cursor is non-empty, another request should be 157 issued to continue reindexing (App Engine limits requests to 10 minutes). 158 159 * `cursor` (optional) - Query cursor returned by previous call. 160 161 ### /song (GET) 162 163 Returns a song's MP3 data. 164 165 * `filename` - MP3 path from [Song]'s `Filename` field. 166 167 ### /stats (GET) 168 169 Gets previously-computed stats about the database. Returns a JSON-marshaled 170 [Stats] object. 171 172 * `update` - If `1`, update stats instead of getting them. Called periodically 173 by [cron]. 174 175 ### /tags (GET) 176 177 Returns a JSON-marshaled array of strings containing known tags. 178 179 * `requireCache` (optional) - If `1`, only return cached data. Used by tests. 180 181 ### /user (GET) 182 183 Returns a JSON-marshaled [User] object containing information about the 184 requesting user. 185 186 [Config]: ./config/config.go 187 [Play]: ./db/song.go 188 [Song]: ./db/song.go 189 [SearchPreset]: ./config/config.go 190 [Stats]: ./db/stats.go 191 [User]: ./config/config.go 192 [cron]: https://cloud.google.com/appengine/docs/standard/go/scheduling-jobs-with-cron-yaml