3

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?

Zdenek
  • 3,653
  • 27
  • 34
Jev Björsell
  • 891
  • 1
  • 9
  • 25
  • Are you referring to resource attributes – properties of a resource or to a particular HTTP message-body (request / response) attributes? – Zdenek Feb 18 '14 at 21:07
  • I'm looking to state the datatype for each resource attribute. I'd also like to offer additional information. Imagine a attribute called "ip", which would be a string, I'd like to also state that it can be a ipv4 or ipv6 address. All of which is easy to do in markdown, but I'm wondering if there is a convention, that can possibly add more value. Thnx. – Jev Björsell Feb 18 '14 at 21:25

1 Answers1

2

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
Zdenek
  • 3,653
  • 27
  • 34
  • Thank you, you answered my specific question on convention/syntax for modelling resource attribute data types. You also answered questions I did not ask, how to model state machines. This is, or I should be say _will be_ awesome. I'm delighted to see the modelling of state-machines. I'm looking forward to the Resource Blueprint support being added. Hopefully that will be soon. – Jev Björsell Feb 19 '14 at 14:53