Search code examples
apiblueprintapiary.ioapiary

What is the convention to specify data types of attributes in apiary.io markdown?

The apiary.io list resource attributes in point form. Is there a specific convention to show what data type these attributes are, or met data specifying formats?

Solution

  • At the moment there is not convention for discussing resource's attributes in the API Blueprint. What comes close is planned Message-body Attributes Description.

    But I feel what would be the real solution is what the concept of a future API Blueprint – Resource Blueprint proposes under semantic data definition (of a resource). Refer to the example resource blueprint.

    So while none of the previous is implemented, if you are looking for a convention, I would suggest consider the one as proposed in resource blueprint e.g.:

    # Resource [/resource]

## Attributes

+ ip (string) ... ipv4 or ipv6 address associated with the resource
+ some-other-attribute (number, optional, `42`) ... a number of something