Skip to content
This repository has been archived by the owner on Nov 8, 2024. It is now read-only.

Affordances #2

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Affordances #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions draft/affordances.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
RFC: XXXX
Author: Kyle Fuller
Status: Draft
Created: 2015-09-21
Last Modified: 2015-09-21
---

# API Blueprint RFC XXXX: Affordances

## Table of Contents

- [Abstract](#abstract)
- [Rationale](#rationale)
- [Example](#example)

## Abstract

This RFC proposes that you can define affordances (link relations) that an API
resource or action provides.

## Rationale

This RFC proposes adding an `Affordances` section into API Blueprint that
sits under a resource or action providing the affodances that it provides.

### Example

To describe affordances from a `Question` resource to two other resources, we
can describe them within the affordances section as follows:

```apib
## Question [/question/{id}]

+ Parameters
+ id: 1

+ Affordances
+ `create_comment` (Comments[create])
+ `author` (User)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

```

Where `Comment` is a resource named `Comment` that has a `create` relation
identifier and User is another resource.

```apib
## Comments [/comments]
### Create Comment [PUT]
+ Relation: create

## User [/user/{username}]

+ Parameters
+ username
```