How to specify an optional element for json request object

Question

In an API project, I want 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 can I tell an API reader that age is optional in an API call, but still shows that it is an integer?

~ Colin

Answer 1

There is currently no special support for this. However, there are several ways to achieve this.

My preference is to discuss this in the description of the request using markdown formatting to your liking, for example:

 ### 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 the http://docs.gtdtodoapi.apiary.io folder collection resource for a further example.

You can also always specify a JSON scheme describing the payload of the body. Pay attention to the dedicated support for discussing the attributes of the message body during the creation process ( https://github.com/apiaryio/api-blueprint/issues/25 )

Answer 2

I recommend a document field table like this.

 ### 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 field table: http://i.stack.imgur.com/cxocx.png