How to specify an optional element for a json request object

I

2

8

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

Interlocution answered 29/3, 2014 at 17:8 Comment(0)

P

2

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)

Peoples answered 1/4, 2014 at 5:3 Comment(1)

Thanks, I was adding comment as per your first example but prefer your second example - I may do a slight tweak and add a heading and just list the optional parameters. – Interlocution 2/4, 2014 at 12:32

E

4

I recommend table of document fields like this one.

### Source Fields

| field      | required | type | example                                | description |
|------------|:-:|-------------|----------------------------------------|-------------|
| name       | * | string      | `average-lead-time-frontend`           | Unique name for machines, used as reference key and for url usage. |
| title      | * | string      | `Average Lead Time Frontend`           | Title for humans. |
| sourcetype | * | string      | `team-avgLeadTime`                     | Source type identificator. |
| groups     |   | list        | `["engagement-analytics", "builder"]`  | List of groups where entity is member. |
| options    |   | object      | `{ "team": 21926 }`                    | Addition options for sourcetype. |
| data       |   | list        | `[70.3, 31.8]`                         | Actual data held by Source. |

Generated table of fields: https://i.sstatic.net/cxocx.png enter image description here

Ento answered 9/4, 2014 at 9:3 Comment(0)

P

2