Collections of modeled resources

[jrep]

How do I combine models and collections? How about models and nested resources?

Commonly of course, one needs some calls that affect some particular object, and others that relate to a collection of such objects.

• GET /resources => list of [resource, resource, ...]
• POST /resources => creates a new resource, returns it
• GET /resources/{id} = get a particular resource
• DELETE /resources/{id} => delete a particular resource

So, this? (Hint: nope! The Model-speak for "Resources body is a bunch of Resource" shows no error but doesn't expand)

# Resources!
## Group New Resources
### Resource [/resource]

+ Model (application/json)
    + Headers

            Accept: application/json

    + Body

            "x": {
                "y": {
                    "z": true
                }
            }

#### Get a Resource [GET]

+ Response 200

    [Resource][]

### Resources [/resources]

+ Model (application/json)

    + Headers

            Accept: application/json

    + Body

            [
                [Resource][],
                ...
            ]

#### List Resources [GET]

List all the Resources owned by this user.

+ Request

    + Headers

            Accept: text/html
            Content-Type: text/plain

+ Response 200 

        [Resources][]

[zdne]

@jrep This is currently not possible. Assets aren't expanded / introspected. Doing so would lead to introduction of escaping [ and ]s in JSONs (or other assets types).

As per our previous discussion, and the roadmap plans, the API Blueprint will support modeling of embedded (related) resource. This will be achieved on attributes description level (aka MSON) as discussed here #25 .

I plan to propose the syntax for the MSON & API Blueprint integration during the course of the week. It might look like this (omitting, unnecessary JSON blobs)

# Resources!
## Group New Resources
### Resource [/resource]

+ Model (application/json)

    + Attributes (object)
        + x 
            + y
                + z: true

    + Headers

            Accept: application/json


#### Get a Resource [GET]

+ Response 200

    [Resource][]

### Resources [/resources]

+ Model (application/json)

    + Attributes (array)
        + (Resource)

    + Headers

            Accept: application/json


#### List Resources [GET]

List all the Resources owned by this user.

+ Request

    + Headers

            Accept: text/html
            Content-Type: text/plain

+ Response 200 

    [Resources][]

This will connect the model of Resources with the one of Resource.

Note there is a problem with your blueprint on line 52 (extra tab):

warning: (5)  found a possible 'Resources' model reference, a reference must be directly in the message-body section, indented by 4 spaces or 1 tab, without any additional sections :706:18

[michaelgwelch]

And will you be able to use one or more models to define a new model?

It is often the case that smaller models are contained within larger models. I like the way the github folks nest their models in their documentation which is then generated using custom nanoc rules. I can't tell from this MSON example if that would be possible.

Their models are actually defined in a ruby script: https://github.com/github/developer.github.com/blob/master/lib/resources.rb

And if you example that file you can see they can programmatically embed one json object within another.

Any of these ruby objects can then be referenced from Markdown (see their README https://github.com/github/developer.github.com scroll down to JSON Resonse section https://github.com/github/developer.github.com#json-responses)

Without this an API document is bound to contain lots of redundancies and if a "sub-model" changes, a lot of find/replace will need to be done.

I've been pursuing using api blueprint in a nanoc project. But I need a custom ruby filter to invoke the aglio javascript.

[michaelgwelch]

I think the answer to my question is yes, MSON will support such a thing: https://github.com/apiaryio/mson

[zdne]

@michaelgwelch

I think the answer to my question is yes

Correct, you will be able to "pull in" attributes descriptors defined elsewhere (albeit it is still unclear whether the source of the definition will be the resource model or some other "data dictionary")

[zdne]

Actual proposal (with examples) to be found in #135