I'm working on some code to try and eliminate boilerplate in Hypermedia API creation. One task here is to identify different affordance types. I'm trying to classify affordance types based on several properties:
1) Does it require a payload
2) Is it safe?
3) Is it idempotent?
Obviously, this is closely aligned with HTTP verbs (partly because I want this framework to be able to reason about how to formulate responses without the user having to get knee deep in HTTP semantics for each affordance they advertise).
I've come up with this table of different types:
// Name Safe Idempotent Payload
// Retrieve Yes Yes No
// Create No No Yes
// Task No No Yes
// Update No Yes Yes
// PartialUpdate No No Yes
// Delete No Yes No
A few comments. First, Create vs. Task has to do with whether something creates a new resource vs. simply trigger some task to be performed on the server. It is a subtle distinction, but one that is meaningful in my domain. That being said, I suspect I will end up having a resource to represent every requested task, so in that case the distinction really falls away. Update vs. PartialUpdate is the usual distinction about whether the request is idempotent or not (i.e., POST/PUT/PATCH)
The goal here is to define affordances in the API according to a scheme like this so that I can determine the HTTP implications (HTTP verb to use, applicable status codes, marshaling and unmarshaling of query strings and request body, etc.)
My main question is...does this kind of classification make sense? Is it missing anything? Is there some other way I should be looking at this (again, remember the goal is to be able to "automate" much of the HTTP processing).
--
Mike