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