A short description for anyone on how POST, GET, PUT/PATCH and DELETE is enough to express anything you need.

REST APIs only handle “things”…

REST APIs are APIs for handling “things” – your business things. Example of things may be “customer” or “payments” and are always nouns. “pay” however is not a thing as it is a verb.

Your business things are represented in JSON.

Example: Read information about a customer

GET /customers/abc123

200 OK

{
  "customerId": "abc123",
  "name": "Peter Andersson",
  "email": "peter@example.com"
}

REST APIs provide only a few predefined methods (actions) to be performed on these business things.

• GET – read thing(s)
• POST – create things(s)
• PUT/PATCH – update things(s)
• DELETE – delete thing(s)

…so how do we model actions?

For a REST API to provide business actions like “pay bill” or “invite user” – the verbs can be translated to nouns. E.g “pay bill” translates to the noun “bill-payment” and “invite user ” translates to “user-invitation”.

“invite user” can be implemented as the creation of a “user-invitation” by providing an endpoint /user-invitations to be called by the method POST.

Example: Create a user-invitation

POST /user-invitations

{
  "inviter": "Peter Andersson",
  "invitee": "Laura Hanson",
  "message": "Hi, you are invited as a user!"
}

201 Created

{
  "userInvitationId": "xyz456",
  "inviter": "Peter Andersson",
  "invitee": "Laura Hanson",
  "message": "Hi, you are invited as a user!",
  "status": "CREATED"
}

By making a thing of the “invite user”-action this user-invitation thing can be given an id (userInvitationId) and has a life-cycle. By adding a status to a user invitation we also get a good way to represent acceptance or rejection of an invitation.

Enabling functionality to accept or reject an invitation does not require much design work. By providing and endpoint /user-invitations/{id} for PATCH to update status we are done.

PATCH /user-invitations/xyz456

{
  "status": "ACCEPTED"
}

200 OK

{
  "userInvitationId": "xyz456",
  "inviter": "Peter Andersson",
  "invitee": "Laura Hanson",
  "message": "Hi, you are invited as a user!",
  "status": "ACCEPTED"
}

If you find this useful and want more stuff like this – follow me on LinkedIn.

/Niklas