Affordances

[kylef]

This is a draft proposal to allow the ability to define affordances an API resource or action may provide.

[pksunkara]

transitions from a resource

Did you mean to say transitions of a resource? Because otherwise I don't understand what you mean by this sentence. Even more especially if you take the sentence above this line into mind.

[pksunkara]

Without understanding the Abstract and Motivation, I can not go through Proposed Syntax and Example.

[pksunkara]

https://github.com/refractproject/rfcs/blob/master/text/0002-clarity-api-description.md#transitions-at-root

You said in slack that this RFC is about the above link. The above link is about allowing Transition (Element) to be nested directly under transitions Category Element under the root element. This is something which was added to allow other API Description formats to use API Description Namespace. API Blueprint doesn't have anything do here.

[zdne]

@kylef I am not sure this is actually needed. Why you simply cannot define a root as a resource and nest actions underneath it?

# Root Resource [/]
## Retrieve Questions [GET /questions]
+ relation: questions

...

Furthermore this does not solve the main problem at the moment - that the actions need to be nested.

[kylef]

I've completely rehauled this PR. Please take another look.

[danielgtaylor]

I think I'm missing something because it's not clear to me at all what this is solving, either by the example or the description above. I understand that the goal is to allow a client to understand link relationships between resources or arbitrary actions, but what does the above actually get me as a client? I'm wondering:

• What are the create_comment and author strings? Are they just an identifier or would an implementor be expected to use these to provide something like e.g. my_question.create_comment(params)? I think any update to the spec should describe why these names exist.
• How would I access the author? Presumably the question would have an attribute called author_id or something that would be taken as a parameter into the author relationship when calling /user/{username}. Where is the link between my_question.author_id and /user/{username} defined here? What can I actually do without that link? I know an author may exist and that the author may have a URL, but really nothing else.
• Similar to the previous point, I assume create_comment would require some kind of question_id attribute and you'd want to link my_question.id to it, but how with the information provided?
• In the user example, how do you link it to any specific action on the user? How do I know whether to use GET or PUT or something else?

[pksunkara]

@danielgtaylor AFAIK, for example, this is trying to define the _links keyword in HAL. But that raises a lot more questions for me.

Let's take the following example on the HAL spec,

{
    "_links": {
        "self": { "href": "/orders" },
        "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],
        "next": { "href": "/orders?page=2" },
        "ea:find": {
            "href": "/orders{?id}",
            "templated": true
        },
        "ea:admin": [{
            "href": "/admins/2",
            "title": "Fred"
        }, {
            "href": "/admins/5",
            "title": "Kate"
        }]
    },
}

As daniel said above, we really don't know the relations between the Question resource and User resource. Similarly with Comment resource. We can use templated as shown above, but I think some people might prefer the actual values instead of templates. Also, If you look at the above example, how do we define something like the ea:admin?

There has been a bit of work done by @zdne on Resource Blueprint which tries to solve these issues and talks about state machines.

In my opinion, the introduction of Affordances to API Blueprint as it is in this document is an half-attempt at the resource blueprint which I don't think does anything good for us. It might actually hamper the development in the future.

[smizell]

I'd like add a thought or two if I could :)

The main issue I see in this for me is that you cannot define state, so you only get small glimpses of the finite state machine and cannot see the full picture. If this is a baby step toward that, this comment may not be applicable, so treat accordingly.

First: when I see an affordance that simply links to a resource or data structure without defining state of that resource, it does not seem like the transition is fully expressed. Instead of exposing application, it ends up simply exposing linked data. In other words, it feels more like a foreign key in a database rather than an actual FSM transition.

Second: when I see an affordance for an unsafe action, I think that I may want to specify what the client may send for that action, which may be different than what the client can send in a different state. Right now, since this only references the action in the resource and therefore can only reference one section of attributes, you do not have this ability. This is related to the above issue, but is specific to the "form" rather than the resulting state.

Third: Daniel brought up a good point about dealing parameters in these situations. Of course the parameters can be used that are defined in the referenced resource, but what if there are multiple resources being linked? For instance, say your Question resource can have multiple authors. This would lead to multiple affordances for authors. I haven't really seen this addressed around the hypermedia space. A client author would want to accommodate for multiple affordances like this, so it would be really nice to somehow describe the potentiality of that situation.

Fourth: I have mentioned this before somewhere, but when I see Relation: create, I am unable to answer the question, "From what state to what state is this relation?" In this example, it suggests this is a relation to a Comments, but it doesn't define the state of that resource. For instance, if the user is not logged in, though they could view comments, they may not be able to create them. This application logic cannot be expressed at the moment.

---

Note: my thoughts here are based on the idea that the API Blueprint is for both client and server implementors. Clients shouldn't care about these states, but a backend developer definitely will.

[zdne]

@kylef please check apiaryio/api-blueprint#288

[pksunkara]

1. Go through wording and finalise this RFC and merge as Draft
2. Send an email to interested parties giving them a deadline when this draft will become accepted