I'm designing a REST API and need advice on whether to use POST or PUT for adding an existing song to a user's collection of favorite songs. Here's my setup: users can view a global list of songs with a GET request to `/api/songs`. Each user has their own list of `favouriteSongs`, and I want to create an endpoint that allows me to add a song (identified by its `id`) to a user's existing favorites list.
For example, a user object might look like this:
```json
{ "user":
{ "id": 1,
"favouriteSongs":
[
{ "id": 123 },
{ "id": 456 }
]
}
}
```
Should I set up the endpoint as either:
1. POST `/api/users/{userid}/favourite-songs` (with the body containing the song id)
2. PUT `/api/users/{userid}/favourite-songs` (with the body containing the song id)
Also, I've read that user id shouldn't be included in the URL or body. Wouldn't using a JWT for the user id be a better choice?
4 Answers
The difference between POST and PUT is crucial! POST is generally for creating new resources, while PUT is about updating existing resources. In your case, since you're adding a song to a user's favorites, you'd typically use PUT if you intend for the request to always result in the same state. However, you might want to consider using POST here instead since you're essentially creating a new link to an existing resource (the song) within the user's list.
Using POST also allows you to avoid duplicates, as it creates new entries rather than potentially overwriting the whole favorites list like PUT would.
If you follow the standard URI patterns, consider creating a dedicated endpoint for favorite songs. For example:
- GET `/api/users/{user id}/favorites/songs/` to fetch all favorite songs.
- PUT `/api/users/{user id}/favorites/songs/{song id}` to either create a new favorite relationship or replace it, and DELETE to remove a song. This way, your API remains predictable and easy to work with.
Interesting point about the user id. It makes sense to include the user id in the URL, but validating it against the JWT is a good practice. This way, your API can be more secure while maintaining clarity.
True! Keeping user ids in the URL also helps in cleaner API design, but ensure that you validate them properly to avoid any mismatches.
I'd go with PUT since you're editing the existing favorite list. From what I understand, POST is more about resource creation. But if you're worried about the uniqueness of the song in the list, you could design the API in a way to check for duplicates before adding.
But remember, PUT usually requires the full representation of the resource being updated. If your intention is to just append a song to the favorites list, it might make more sense to use POST instead.