Should I edit a user meta field with PUT, PATCH, or POST and WP::Editable

Question

I have a simple CPT called App in the backend.

I have added a custom usermeta field called favorite_apps to Users

On the front end, I show a list of apps, and then the user presses a star(☆) icon to add it to their list of favorites ( stored as an array of post_id in the favorite_apps custom user meta field ).

I decided to do this using the REST API and built a custom endpoint:

/wp-json/my-site/v1/users/{user_id}/favoriteapps

Example: /wp-json/my-site/v1/users/555/favoriteapps

This route accepts POST,PUT,PATCH using WP::Editable and GET using WP::Readable.

A GET request returns a list of user 555's current favorite_apps

A POST request, and pass app=123 in the body I add the App ID 123 to app_favorites

For removing an app from the list, I'm not sure. I'm not DELETING the list of favorite_apps, I'm removing one of the items.

It feels natural to use POST and DELETE to add/remove from the list, but:

1. Is there a convention that I can follow when modifying a list of items?
2. Should I be using PUT or PATCH and passing an action as another parameter?
3. Do I have to be concerned about browser support for certain methods?

For reference, this is how I add app 123 to/from user 555 in js/jQuery:

var uid = 555;
var appId = 123;
$.ajax({
    method : 'POST',
    data   : { app : 123 },
    url    : '/wp-json/my-site/v1/users/' + uid + '/favoriteapps',
        success: function( data ){
            // code to tell user of success or failure;
        }
});

Answer 1

Okay, with some great examples from : https://restfulapi.net/resource-naming/ and http://www.restapitutorial.com/lessons/restfulresourcenaming.html I'm going to answer my own question.

ESSENTIALLY, for my use case, I will NOT use PUT but rely on POST and DELETE to collection and singleton endpoints.

Notes:

1. I've omitted the wp-json/my-site-namespace/v1 prepending examples for clarity
2. I've used query strings in POST requests but for clarity, but I'd submit them in the POST body as POST vars and NOT in the query string.

Use GET Requests on single entities or collections

// Gets a collection of users
GET /users 

// Gets the singleton users 3
GET /users/3/favoriteapps

// Gets a collection of user 3 favorite apps
GET /users/3/favoriteapps

Use POST requests only on collection endpoints ( makes sense )

// Create a new user named Joe ( returns the ID )
POST /users?name=Joe ( pass in required params in POST vars )

// Add app 123 to user's favorite apps. Technically, I'm not CREATING
// a new favorite app, which is where I was getting hung up, but 
// in context of user 3, I AM creating a new reference to an existing app

POST /users/3/favoriteapps?app_id=123  ( pass in required app id in POST vars )

USE PUT requests to edit a collection or an entity

In my case, I'm adding and removing known apps to and from the user, so I would NOT support PUT in my implementation, but if I DID implement it I would implement it only on the collection, maybe if I was passing a collection and comparing that collection with what is existing.

// Edit ( replace ) existing apps with list of apps for user 3
PUT /users/3/favoriteapps?apps=123,321,444,111,33

// In my use case, I wouldn't ONLY support PUT to a new favoriteapps
// base url, outside of the user context This would but this would 
// change the app title for app 123 ( obviously for all users' collections )
PUT /favoriteapps/123?title=New+App+Title

Use DELETE requests on single entity endpoints (mostly)**

** Using DELETE on a collection endpoint should delete the whole collection (semantically speaking), which is rarely what you intend. but in some cases, like a clear button to reset the collection to 0 items, you could use it.

// Remove app `123` from favoriteapps collection of user 3
DELETE /users/3/favoriteapps/123

// note: this is another area I got hung up, as I'm not DELETING app 123
// However, in context of user 3, I AM removing it from that user's collection