diff --git a/API.md b/API.md new file mode 100644 index 0000000..ccd2435 --- /dev/null +++ b/API.md @@ -0,0 +1,121 @@ +# API Documentation + +The API can be accessed at `https://d1e7htx1c4j3w0.cloudfront.net/api`. + +## Endpoints + +### POST /auth/token + +Exchanges an authorization code for access and refresh tokens. + +**Headers:** +- `Content-Type: application/x-www-form-urlencoded` + +**Body Parameters:** +- `code` (required): Authorization code from Spotify OAuth flow + +**Returns:** +```json +{ + "access_token": "string", + "refresh_token": "string", + "expires_in": number +} +``` + +Also sets `access_token` and `refresh_token` cookies. + +### GET /me + +Retrieves the current user's Spotify profile information. + +**Headers:** +- `Authorization: Bearer ` (or access_token cookie) + +**Returns:** +```json +{ + "id": "string", + "username": "string" +} +``` + +### GET /artist-name + +Fetches the name of an artist by their Spotify ID. + +**Headers:** +- `Authorization: Bearer ` (or access_token cookie) + +**Query Parameters:** +- `artistId` (required): Spotify artist ID + +**Returns:** +```json +{ + "artistName": "string" +} +``` + +### GET /artists-albums + +Retrieves all albums for a given artist, including albums, singles, compilations, and appearances. + +**Headers:** +- `Authorization: Bearer ` (or access_token cookie) + +**Query Parameters:** +- `artistId` (required): Spotify artist ID + +**Returns:** +```json +{ + "artistsAlbums": [ + { + "id": "string", + "name": "string" + } + ] +} +``` + +### GET /artists-tracks + +Fetches all tracks by a given artist. + +**Headers:** +- `Authorization: Bearer ` (or access_token cookie) + +**Query Parameters:** +- `artistId` (required): Spotify artist ID + +**Returns:** +```json +{ + "artistsTracks": [ + { + "id": "string", + "name": "string" + } + ] +} +``` + +### GET /create-playlist + +Initiates asynchronous creation of a playlist containing all tracks by the specified artist. The playlist will be created in the user's Spotify account. + +**Headers:** +- `Authorization: Bearer ` (or access_token cookie) + +**Query Parameters:** +- `artistId` (required): Spotify artist ID + +**Returns:** +```json +{ + "message": "Playlist creation accepted" +} +``` + +Note: This endpoint returns immediately while playlist creation continues asynchronously. diff --git a/README.md b/README.md index c56764a..c004b3b 100644 --- a/README.md +++ b/README.md @@ -1 +1,72 @@ # all-tracks + +all-tracks generates a complete playlist of every track by any Spotify +artist—no hunting for user-made playlists required. + +## Demo + +https://github.com/user-attachments/assets/623dcf1d-d8a1-46ed-9d7f-eb16c18ca77c + +Users visit the site [here](https://d1e7htx1c4j3w0.cloudfront.net/). Once +authorised, they enter an artist's Spotify URL and click 'Create Playlist'. +After a short delay, a playlist with all the artist's tracks is created in the +user's Spotify account. + +Unfortunately Spotify does not allow apps developed by individuals to leave +'development mode' (see +[here](https://developer.spotify.com/documentation/web-api/concepts/quota-modes) +for more details). This means to use the app your account must be allow-listed, +so please contact me if you wish to use the app! + +## Installation of dependencies + +Clone repo and run `yarn`. + +## Tests + +Run `yarn test` to run the Jest tests. However, only the small tests will work +as the medium and large tests require secrets on your machine. Contact me to +obtain them. + +Run `yarn test:cypress` to run the Cypress tests. Secrets are not required for +these tests. Run `yarn cypress:open` to open cypress. The tests can also be run +from here. + +## API endpoints + +The API can be accessed at `https://d1e7htx1c4j3w0.cloudfront.net/api`. +See [API.md](API.md) for detailed endpoint documentation. + +## Architecture + +### Back-end architecture + +![Back-end Architecture](docs/back-end-architecture.png) + +The back-end consists of an API Gateway, a Lambda to serve the gateway and a +downstream Lambda to create playlists. The Lambda to create playlists is invoked +asynchronously by the API Lambda. Playlist creation is handled in this way +because creation can take a long time for artists that have a lot of tracks. + +### Front-end architecture + + + +The front-end is simple HTML and JavaScript. It is served from an S3 bucket +behind a CloudFront Distribution. Authorization is handled through Spotify's +OAuth 2.0 flow. Once authenticated, the browser can make requests to the API. + +## Technical decisions and process + +- All infrastructure is managed by Terraform. +- TDD is used throughout development. +- CI/CD is handled by GitHub actions. +- No external libraries are mocked out. A wrapper is created around functions + that use external libraries. Small tests are used to test the functions that + use the wrapper, and medium or large tests are used to test the wrapper + itself. For example, a wrapper is used to make requests to Spotify. Functions + that use this wrapper have small tests that mock the wrapper out. The wrapper + itself is tested with medium tests that make actual calls to the Spotify API. +- As this is a POC the front end is kept purposely simple. Ideally a framework + would be used to allow easier development and testing. +- Cypress is used to test E2E to closely simulate user interactions. diff --git a/docs/all-tracks-demo.mp4 b/docs/all-tracks-demo.mp4 new file mode 100644 index 0000000..4665363 Binary files /dev/null and b/docs/all-tracks-demo.mp4 differ diff --git a/docs/back-end-architecture.png b/docs/back-end-architecture.png new file mode 100644 index 0000000..55a76ee Binary files /dev/null and b/docs/back-end-architecture.png differ diff --git a/docs/front-end-architecture.png b/docs/front-end-architecture.png new file mode 100644 index 0000000..e8529c5 Binary files /dev/null and b/docs/front-end-architecture.png differ