How to put resource creation and other methods in the same group?

Question

Suppose I create a resource with POST /resource and that yields an id on the response body, and then I use that id to retrieve my resource with GET /resource/{id}.

How do I put these two requests in the same API Blueprint group ?

Apparently a group has only one endpoint, which makes the following look like you would create a resource with POST /resource/{id} which is not true, because you don't even have an id at this point.

## Resource [/resource/{id}]

### Creating the resource [POST]

+ Response 201
    + Body

            {
                "id": "uuid"    
            }

### Retrieving the resource [GET]

+ Parameters
    + name (string) ... The name of your collection.

+ Response 200
  + Body

          {
              "id": "uuid"  
          }

I looked at the examples but couldn't find an example of creating and retrieving a specific resource. Am I doing this the wrong way ?

score 1 · Accepted Answer · answered Aug 27 '14 at 01:23

1

Technically /resource and /resource/123456 are not the same resource identifiers. For more details take a look at An HTTP Resource is a lot simpler than you might think.

Personally, I prefer to think about this as a "resource" and "collection of resources". Where the create operation usually means "create and insert into collection". The collection has one URL (for example /mighty/frogs/in/the/wood/ or /resources) and the a resource from the collection has another URL (for example /123124 or /resources/1234) Note the point is the absolute values of URLs are irrelevant as long as they are unique – with that being said it is usually a good idea to have sane URLs.

Back to blueprint:

# Collection of Resource [/resouces]
## Create [POST]

...

### List all Resources [GET]
...

# One Resource [/resource/{id}]

## Retrieve the Resource [GET]    
...

Hope this helps.

answered Aug 27 '14 at 01:23

Zdenek

3,653
27
34

Your blueprint reads "create a collection of resources", that's what I was trying to avoid. Still if you're thinking of just a resource and it's lifetime, you have creation, update, retrieval and deletion. POST PUT GET DELETE, and it seems that those should maybe belong to the same group. Worst thing is that my API actually has a resource called `collection` so then I would have to call that group `Collection of Collections`... I hate naming things.. – João Pinto Jerónimo Aug 27 '14 at 01:32
However you DO create a resource sending post to another resource (POST /resources vs. GET /resources/12312). Basically what REST is - is manipulation with resources through their representations based on available affordances. This is not OOP :) But again, this is my point of view and your mileage may vary – Zdenek Aug 27 '14 at 18:01
1

Please also refer to this discussion for the planned syntax updates related to this – https://github.com/apiaryio/api-blueprint/issues/88#issuecomment-53617073 – Zdenek Aug 27 '14 at 18:20
@Zdenek Great, I was looking for it. – Md. Zubaer Ahammed Nov 18 '21 at 13:56

How to put resource creation and other methods in the same group?

1 Answers1