Resources Relations

[zdne]

Expressing relations between resources through available actions (affordances).

Currently a resource can define only actions defined on the respective resource.
However, in reality, a resource may afford an actions that are not limited to the resource itself.

Inline Action

In-place definition of another Resource.
This section would follow standard rules for
Action Sections.
With the exception that a different URI may be used.
Defining an in-line action does not create a new API Blueprint Resource.

# Task [/tasks/{id}]

+ Parameters
    + id

## Retrieve Task [GET]

+ Response 200

        { ... }

## Delete Task [DELETE]

+ Response 204

## Create New Task [POST /tasks]

+ Request

        { ... }

+ Response 200

        { ... }

## List All Tasks [GET /tasks{?parent,group_name,status,paused,priority}]

+ Parameters
    + parent
    + group_name
    + status
    + paused
    + priority

+ Response 200

        { ... }

Relation Identifiers

Optionally it SHOULD be possible to specify additional link relation types as specified in the RFC 5988.

The syntax should be:

+ Relation: <link relation identifier>

For example:

# Task [/tasks/{id}]

+ Parameters
    + id

## Retrieve Task [GET]

+ Relation: task
+ Response 200

        { ... }

## Delete Task [DELETE]

+ Relation: delete
+ Response 204

## Create New Task [POST /tasks]

+ Relation: create
+ Request

        { ... }

+ Response 200

        { ... }

## List All Tasks [GET /tasks{?parent,group_name,status,paused,priority}]

+ Relation: list
+ Parameters
    + parent
    + group_name
    + status
    + paused
    + priority

+ Response 200

        { ... }

---

Update: Referencing another actions is not planned at the moment

Referencing Another Resource's Action

Affording another Resource action on this resource. Such a section would not have any other content except its definition.

## User [/users/{id}]
### List [GET]
+ Response 200

        ...

## Post [/posts/{id}]
### Retrieve [GET]
+ Response 200

        ...

### Author: [User.List][]

[jrep]

Several comments:

1. Yes! Highly desirable!

2. Are you saying that form 1, "Inline Action," is already described by Action Section? 'Cause I don't see it there, can you guide me? Or are you just saying "when it's written, that's where it will go" (which makes sense to me)?

3. Are there interactions here with the RESTful RMM Level 3 "Hypermedia Controls" notion? There's clearly a relationship, but I'm not clear on whether that needs description or machination. It might, for example, constitute a third form:

   Post [/posts/{id}]

   Retrieve [GET]

   • Response 200

     {
         "items": [ {...} ],
         "links": [
              { "rel": "self", "link": [Post.List][] },
              { "rel": "author", "link": [User.List][] }
          ]
     }
     

     What I just wrote is not, I think, quite right: what's wanted in those [...][] places is a link, not an expanded model/body. Is there Blueprint syntax for "link to ..."?

[zdne]

Ad 2

Or are you just saying "when it's written, that's where it will go" (which makes sense to me)?

Correct.

Ad 3

Yes, this proposal is indeed meant to give you the option to list every relation (or affordance, if you will 😄) available for the resource, should you choose to design your API this way.

This is could be beneficial for many things including:

• capturing relations between resources in documentation
• building API as a finite state machine
• supporting HATEOAS architectural style
• ultimately, using a hypermedia media type (HAL, Siren, etc.), blueprint (parser) should generate the representations for you so you do not have to do something like { "rel": "self", "link": [Post.List][] }

Note the relation name should be covered in the Action specification (either equal to its name, or explicitly defined). If you are interested in this direction of API architectural style you can find more on it here.

[dubcanada]

Inline actions... When could we expect this? As it is a requirement for my API.

[zdne]

@dubcanada there is no ETA on this yet, but I would like to see some progress on this around the Q3-Q4.

Would you please care elaborate on what are your expectations of it – why do you require such a functionality?

Thanks!

[psynaptic]

What's the current method for representing the following:

• POST /entity
• GET /entity/{id}
• PATCH /entity/{id}
• DELETE /entity/{id}

I want one top-level "Entity" resource that describes the actions as laid out above. I guess this is what the suggested inline actions are for.

At the moment, it seems like I need to specify 2 top-level resources, one at /entity and the other at /entity/{id}. Is this correct?

[zdne]

@psynaptic

Currently, in a resource description, it is possible to describe only actions that are performed with the respective resource. Put in contrast offering (affording) actions on a resource that are not directly manipulating the resource in question – this is something this issue should cover.

Please see this question at Stack Overflow.

Moving forward. With this feature implemented you will be able to add an arbitrary action to a resource even it is not manipulating the respective resource directly (/entity/12234 and /entity and /entity/abcd are three different resources!) :

# Entity [/entity/{id}]

# Retrieve [GET]
Retrieving this resource

# Create [POST /entity]
Manipulating another resource

With this, the idea is the /entity will not have its separate resource entry (even strictly speaking it is its very own resource you API is offering). But again, at the time being you need to break this into two resources.

[psynaptic]

@zdne

Thanks for responding so promptly.

I agree that each distinct URI is a separate resource but to me, a single entity (as in the concept) is what is being added; I see the entity as an individual representation of an instance of the model.

Practically, if I use the suggested (and perhaps semantically more appropriate) alternative with a collection that has query parameters, they are "inherited" by the creation action:

## Tasks Collection [/tasks{?parent,group_name,status,paused,priority}]

## Create a Task [POST]

Results in a create action URI of:

POST http://myapi.apiary-mock.com/tasks?parent=parent&group_name=group_name&status=status&paused=paused&priority=priority

[zdne]

POST http://myapi.apiary-mock.com/tasks?parent=parent&group_name=group_name&status=status&paused=paused&priority=priority

This is a bug in current Apiary documentation. If you do discuss these parameters under let's say a GET section of Tasks Collection these should be displayed there and only there.

We are currently working on the fix.

[zdne]

So if the blueprint would be something like this

# Tasks [/tasks{?parent,group_name,status,paused,priority}]

## List Tasks [GET] 
+ parameters
    + parent
    + group_name
    + status
    + paused
    + priority

+ response 200

        { ... }

## Create a Task [POST]
+ response 201

You should really see only POST /tasks in the documentation.

[psynaptic]

Just for clarity, that's basically exactly what I have:

https://gist.githubusercontent.com/psynaptic/6c19497456bb2d903233/raw/215fc3bdf066fe028c676c818863146756913d1c/gistfile1.md

Thanks for confirming that it is a bug and not simply misunderstanding on my part.

[zdne]

@psynaptic yep that looks correct! The bug is on our side – sorry about this I will do my best to fix this as soon as possible!

[zdne]

@psynaptic the parameters rendering bug discussed here #88 (comment) has been fixed in Apiary.

[SyRenity]

Any idea when it will be fixed on Apiary site?

[fosrias]

@zdne Just to be clear. Is this addressing the following scenario:

# Tasks 

## List Tasks [GET /tasks{?parent,group_name,status,paused,priority}] 
+ parameters
    + parent
    + group_name
    + status
    + paused
    + priority

+ response 200

        { ... }

## Create a Task [POST /tasks ]
+ response 201

[zdne]

@fosrias not exactly, you still have to have a top-level resource defined Tasks in this case.

e.g. # Tasks [/tasks], not what you are describing is already possible (by document the parameters only on relevant action:

# Tasks [/tasks{?parent,group_name,status,paused,priority}]
## List Tasks [GET] 
+ parameters
    + parent
    + group_name
    + status
    + paused
    + priority

+ response 200

        { ... }

## Create a Task [POST]
+ response 201

[zdne]

@fosrias

This would be a better example, however I would still recommend defining Tasks and Task as two separate resource (collection of elements and one element):

Update: I have edited the original post accordingly

[fosrias]

@zdne Concur on the separate resources. Probably was not paying close
enough attention. Will you be able to have a path on the resource element
and then override it if you want on an action under the resources. Seems it
should work that way so that you only modify actions if necessary. More DRY.

On Fri, Feb 20, 2015 at 4:36 AM, Z notifications@github.com wrote:

@fosrias https://github.com/fosrias

This would be a better example, however I would still recommend defining
Tasks and Task as two separate resource (collection of elements and one
element):

Task [/tasks/{id}]

• Parameters

  • id

    Retrieve Task [GET]

• Response 200

  { ... }
  

  Delete Task [DELETE]

• Response 204

  Create New Task [POST /task]

• Request

  { ... }
  

• Response 200

  { ... }
  

  List All Tasks [GET /tasks{?parent,group_name,status,paused,priority}]

• Parameters

  • parent
  • group_name
  • status
  • paused
  • priority

• Response 200

  { ... }
  

—
Reply to this email directly or view it on GitHub
#88 (comment)
.

[pksunkara]

Defining an in-line action does not create a new API Blueprint Resource.

What if I want it to be separate API Blueprint Resource? The use case here is that I want to have a Resource which contains only 1 action. So, instead of writing Resource header and Action header, I want to combine them both in a single line.

[zdne]

Both "inline actions":

## Create New Task [POST /tasks]

and "action relation types":

+ Relation: create

are now supported in Apiary (as of 1A8). Please let us know how do you like these new features!

---

Also refer to:

• Action Section
• Relation Section