I'm working on a REST API and I'm a bit confused about whether to use POST or PUT when adding an existing song to a user's favorites. Here's the situation:
- Users can access a global list of songs via `GET /api/songs`.
- Each user has their own favorites list called `favouriteSongs`.
- I want to create an endpoint to add a song (by its `id`) to a user's favorites.
Here's what I'm considering:
1. **POST `/api/users/{userid}/favourite-songs`** (body contains song id)
2. **PUT `/api/users/{userid}/favourite-songs`** (body contains song id)
I'm also curious about whether I should include the user id in the URL or the JWT token. Any thoughts on the best approach?
4 Answers
When it comes to REST APIs, it's all about whether your endpoint is idempotent or not. If adding the same song twice would change the state (like adding duplicate favorites), then you should go with POST. Conversely, if multiple requests don't change the outcome, PUT could work. I typically lean towards POST for adding favorites and prefer to see the user ID in the URL for clarity. Also, instead of having `POST /users/{userid}/favourite-songs`, using `POST /users/{userid}/add-favorite` makes it clearer that you're adding something specific.
I think using POST for adding a song to the favorites makes sense, while PUT would be more fitting for updating an entire list. Remember these two lists are separate entities, so for adding a song, POST would be appropriate. You could also include the song ID in the URL since the song is already an existing resource, rather than requiring it in the body.
Absolutely! It gives more flexibility. It could also make sense to allow for a POST with multiple song IDs in the body, effectively letting users create a favorites list. If they tried to add songs to an already made favorites list, then a 409 status would be a logical response.
Honestly, I think it's more user-friendly to create URLs that narrate the action instead of strictly adhering to HTTP verbs. Something like `POST /api/users/{userid}/add-favorite-song-to-list` is self-explanatory. Who cares about the technicalities of POST or PUT, if users can intuitively understand the URL? And, I’d prefer a consistent success code like 200, rather than forcing myself to memorize a whole list of status codes.
If you're planning to share this API widely, consider using JSON patch (RFC 6902). It can handle a variety of use cases and provides a flexible way to handle updates without needing to fit strictly into the POST or PUT mold.
That's a great point! Clarity in the endpoint is crucial, and by using descriptive actions in the URL like you suggested, it definitely helps users understand what they're doing without having to dive deep into the docs.