What is the correct format for denoting that an input parameter is a date/time in Apiary?

Question

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?

Gilkey

Answer 1

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

Pneumonia

What if the date is auto-generated by the backend? (auto timestamp) – Dislocate

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. – Pneumonia

I was basically wondering if there is a way to specify a field which not required, but auto generated by the backed – Dislocate

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 – Dislocate

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. – Pneumonia