Nested Message-body Attributes

[xyzjace]

RE: the tweet I sent to @apiblueprint and with @zdne.

We're currently documenting an API which takes POST params of the form:

some_object: {
      a_required_field: {},
      an_optional_field: {},
      perhaps_an_object: {
          a_nested_nested_field: {}
      },
},
some_other_object: {
      a_required_field: {},
      another_required_field: {},
      further_required_field: {},
},
etc..

and we'd love to see the ability to represent this nesting of parameters, or even describing of an object's optional/required parameters in the Blueprint spec.

I envisage it may look something like:

+ Parameters
    + currency (optional, string, `` ) ... A standard currency
    + merchant (required, merchant, `` ) ... A merchant object
        + reference_number (required, string, `` ) ... A merchant's external reference number
        + name (optional, string, ``) ... A merchant's full name
    + product (required, product, `` ) ... A product object
        + code (required, string, `` ) ... A product code

Or perhaps it could take the form:

+ Parameters
    + currency (optional, string, `` ) ... A standard currency
    + merchant (required, merchant, `` ) ... A merchant object
        + Parameters
            + reference_number (required, string, `` ) ... A merchant's external reference number
            + name (optional, string, ``) ... A merchant's full name
    + product (required, product, `` ) ... A product object
        + Parameters
            + code (required, string, `` ) ... A product code

I think the first option would be a lot cleaner.

Are there any plans on implementing something along these lines? Or how would we go about getting that in motion?

Cheers,
Jason

[zdne]

@xyzjace

Personally I really like this idea. I do plan to introduce description of message-body parameters (a.k.a. state or attributes) in the upcoming API Blueprint format - #25.

Originally I was thinking about utilizing some sort "JSON pointer" or just something simple as MongoDB dot notation but this seems really natural and thus might be a better fit for Markdown documents.

It could even be extended for URI parameters. Intriguing.

Let's merge this issue with #25. OK?

Regarding a time frame: I probably won't have time to start working on it before November, so if you could contribute to speed it up it would be great. Both a pull request to the API Blueprint specification & examples as well as to the actual parser are welcome.

[BRMatt]

Sorry if I'm misunderstanding the problem, but couldn't this be solved by using the schema section to document a JSON schema?

[zzen]

@BRMatt probably could - all of parameter descriptions are redundant to Schema. It's a simpler syntax for people who wouldn't go through writing a full-spec schema.

[BRMatt]

@zzen Awesome, thanks for clarifying that.

[zdne]

@BRMatt

You are indeed correct. You can achieve similar, if not all, of this by using a JSON Schema.

However while following should be roughly equivalent:

Body:

+ model (application/json)
    + body

         ```
         { "message": "Hello World" }
         ```

Schema:

+ model (application/json)
    + schema

        ```
        {
            "type":"object",
            "$schema": "http://json-schema.org/draft-03/schema",
            "id": "http://jsonschema.net",
            "required":false,
            "properties":{
                "message": {
                    "type":"string",
                    "id": "http://jsonschema.net/message",
                    "required":false
                }
            }
        }
        ```

Attributes:

+ model
    + Parameters
        + message (string, `Hello World`)

The parametric approach has arguably two huge benefits:

1. It is somewhat more natural to write and read

   While almost every API is now utilizing the JSON media type not everybody has embraced the JSON Schema. And even if you are using the JSON schema you might find it easier to use Markdown for key description from within Markdown document than inside a JSON (description) field.

2. It is agnostic to a media type.

   Being agnostic to media type opens a whole new world of possibilities. For example one can genereate XML, JSON or even a CSV from just one model definition. Or go even beyond and utilize referencing and user-provided tokens etc.

[zdne]

Note: I have renamed this issue from Nested Parameters to distinguish between URI (template) parameters and entity body properties.

[zdne]

To be addressed with #25