11

I am editing some Apiary documentation on a project I am working on, and need to denote that a parameter to one of my API calls is a datetime string. Apiary seems to be choking on the formatting of this parameter, so I'm wondering what the suggested approach for documenting this parameter in Apiary would be.

To demonstrate, I took the standard default docs from Apiary and modified the Choice documentation to take a datetime object like so:

## Choice [/questions/{question_id}/choices/{choice_id}/{datetime}]

+ Parameters
    + question_id: 1 (required, number) - ID of the Question in form of an integer
    + choice_id: 1 (required, number) - ID of the Choice in form of an integer
    + datetime: 2015-05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) associated with this choice

The end result of this is the following text:

datetime
05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) that all returned events should be greater than or equal to Example: 2015.

This is clearly wrong, even write down to the example value. The dash (-) is a special character that is causing grief here. What is the recommended approach for doing this right?

Chris
  • 3,693
  • 4
  • 21
  • 30

1 Answers1

24

You should be able to use backticks as an escaping sequence. Also please note that there is no such type as date. You should use string:

+ datetime: `2015-05-05T12:30:00` (optional, string) - The date/time (ISO8601 format) associated with this choice
Honza Javorek
  • 6,241
  • 5
  • 42
  • 63
  • What if the date is auto-generated by the backend? (auto timestamp) – Oleg Belousov Aug 20 '17 at 14:30
  • I don't understand the comment. The original question is about a design document where one specifies what should be in HTTP requests or responses. Whatever your backend generates, it's up to you to correctly describe it. It's probably either string or number. – Honza Javorek Aug 22 '17 at 19:04
  • I was basically wondering if there is a way to specify a field which not required, but auto generated by the backed – Oleg Belousov Aug 22 '17 at 19:07
  • Now that I learned that every method (GET, POST,PUT) has its own doc, it makes more sense to me, as 'required' means something else essentially per every method – Oleg Belousov Aug 22 '17 at 19:08
  • In request, you do not specify such fields. In response, you would mark it as `required` (always present) or `fixed` (if the value is constant - which usually isn't for timestamps) and you would note in the description that the field is generated by the server automatically and is read-only. – Honza Javorek Aug 22 '17 at 19:10