Many nouns, few verbs

An important part of our system of resources is the idea of limiting the kinds of ways we interact with them. These interactions are retrieval (GET), creation (POST), updating (PATCH), and deletion (DELETE).

This limitation is very important in enabling precise conversations and a clear mental model of our system, but at times it might feel unnatural. You’re going to have to take every single user action and express it with one of these four verbs, which may not be how you’d express this same idea in English. Here are some examples:

• Signing up: creating a User
• Logging in: creating a Session
• Logging out: deleting a Session
• Adding to cart: creating a Cart Item
• Checking out: creating an Order

My advice is to just try to get used to it. It’s okay to speak colloquially about “signing in” as long as there’s a shared understanding of what that means. In fact, this shorthand can be useful—for example, what you and your team call “checking out” may include creating an Order resource as well as creating Shipping Address, Billing Address, and Gift Message resources. This is one of those situations where you just can’t—or shouldn’t—try to represent everything in code. (But do try to write everything down.)

Implementing a new bit of functionality will almost always mean adding a verb that wasn’t already available, or adding a resource that didn’t exist before.

What about PUT?

One HTTP verb that is notably absent from my advice above is PUT. Historically, PUT has been a more popular choice for signaling to the server that the request is meant to update an existing record. However, PUT is more appropriate for replacing the record. There are some instances where the most appropriate thing to do is actually a full replacement, and in those cases you might want to implement a PUT. But it’s not what our collective understanding of “updating” a resource actually means, and it’s probably safe to completely ignore in almost every API you’ll ever build.