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 ?

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