Affordance Types

[Michael Tiller]

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

[Kijana Woodard]

For background, have you already seen and considered H-Factor [1]?

[1] http://amundsen.com/hypermedia/hfactor/

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Michael Tiller]

Kijana,

  Yes.  In fact, my underlying abstract representation on the server side tries to take into account these various factors and then considers the Accept header to determine what media type to use when responding (and what affordances can be represented in the concrete media type chosen).

  But my question here is really unrelated to the media type itself but more about abstractions.  It is about trying to classify all potential "state transitions" or "actions" according to some scheme to understand all the consequences in HTTP handling.  For example, if somebody does a Create type request, then that will be a POST and success means a 201 status code while a Task would be a 202 status code, upon successful completion.

  My goal here is to try and come up with these categories so that I can then hand off lots of the HTTP semantics and I don't have to code it up myself each time.

  Keep in mind, you can poke holes in this since these are just conventions.  I'm not trying to imply that all of HTTP can be some how distilled down to something simpler.  I'm just trying to identify some common conventions and patterns and provide support for them so that people don't have to drop down to low level HTTP (and making sure they get that right!) just to do common stuff.  This is aligned with the principle that "Simple things should be simple and complex things should be possible".

--

Mike

[Kijana Woodard]

Who's the audience for this effort?

[Michael Tiller]

On Wed, Jan 27, 2016 at 5:44 PM, Kijana Woodard <kijana....@gmail.com> wrote:

Who's the audience for this effort?

The audience is developers trying to build APIs.  At the moment, I've got exactly one customer...me.  I'm scratching my own itch here.  Having been down this road a few times, I'm trying to see how much I can reduce the boilerplate and streamline the development of the API.  But I'm trying to see beyond my own immediate requirements.  If I'm going to try and put the effort into this, I want the foundation to be reasonably sturdy...hence the feedback.

--

Mike