Grouping together methods with slightly different URIs

[ChrisZieba]

Is there a way to group together method actions with different URI's? For example, I would like to group together a GET, PUT, and POST method, but the GET and POST have the following URI's /message/{id} whereas the POST does not have the ID.

I am currently creating a sub-group, but this does not seem ideal.

# Group Messages
Group of all messages-related resources.

## Message [/message/{id}]

### Retrieve a Message [GET]

+ Response 200 (text/plain)

        Hello World!

### Update a Message [PUT]

+ Request (text/plain)

        All your base are belong to us.

+ Response 204

## Message [/message]

### Create a Message [POST]
+ Request (text/plain)

        All your base are belong to us.

+ Response 204

[zdne]

@ChrisZieba Just to make sure – is your concern (for grouping) based on the fact how does the rendered documentation look like? Table of Contents in particular?

Also is this related to collection + item of the collection only or would you see a use for it elsewhere?

[ChrisZieba]

@zdne This does concern the rendered output, but not the table of contents. The volusion example on the homepage seems to accomplish what I am after. Specifically, the PUT request for "update a billing address" contains the ID parameter, but the POST request from the same group does not.

[zdne]

@ChrisZieba OK got it.

There are two answers:

1. Quick hack around how Apiary rendered doc works right now:

   If you define the messages collection + message item as a one resource in blueprint and document the id parameter only where you want to see it you will get the result.

   E.g.:

   # Messages [/messages/{id}]
   
   ## Retrieve All Messages [GET]
   + Response 200 
   
   ## Update a Message [PUT]
   
   + Parameters
       + id ... id of the message to update
   + Response 200
   

   However this is not technically correct, as a collection an item in a collection are indeed essentially two different resources. Furthermore repeating a method multiple times will probably lead to a parser warning.

2. Sadly the solution to express the embed relation is not yet available neither in API Blueprint nor in Apiary. It is planned to add it into Blueprint and reflect it in the rendered documentation.

[ChrisZieba]

@zdne Thanks!

[zdne]

@ChrisZieba Wish I had a better news! Sorry about that. Feel free to throw in a comment on what would you see as a the best solution to this.