How to specify an optional element for a json request object

apiblueprint, json

Solution

Currently there is no dedicated support for doing this. However there are few ways how to achieve this.

My preferable is to discuss it in the request description using a markdown formatting of your liking e.g:

### Add a new User [POST]
To add a User send a JSON .....

+ Request (application/json)

    Data about user being created. Where age attribute is optional.

    + Body

            {
                 "name": "A name",
                 "age": 30
            }

or perhaps:

To add a User send a JSON .....

+ Request (application/json)

    Data about user being created. With following attributes are:

    + `name` ... name of the user
    + `age` (optional) ... age of the user

    + Body

            {
                 "name": "A name",
                 "age": 30
            }

See http://docs.gtdtodoapi.apiary.io Folder Collection resource for a futher example.

You can also always specify a JSON schema describing the body payload. Note dedicated support for discussing message body attributes is in the making (https://github.com/apiaryio/api-blueprint/issues/25)

Problem

In API blueprint I am looking to specify an optional json element for a POST message. Example for; ``` ### Add a new User [POST] To add a User send a JSON ..... + Request (application/json) { "name": "A name", "age": 30 } ``` How do I indicate to reader of API that age is optional in API call but still show that it's an integer? ~Colin

Original source