How to format hash-based parameters in the URL when creating Blueprint API doc?

Question

With the Rails Way of adding hashes in the parameter of an URL like so:

 http://api.example.com?person[first]=Jane&person[last]=Doe&person[email][email protected]

How do I format the API Blueprint doc to accommodate a list of available hashes?

• Parameters
  • person[first] (required, string, Jane) ... First name

This is not legal when I execute the document.

Any ideas or tips are welcome!

Avifauna

Answer 1

Per https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2, you must escape [] in URIs. As such, you need to do:

• Parameters
  • person%5Bfirst%5D (required, string, Jane) ...

If you template the URI in your blueprint, you must also escape the [] there as well.

FYI, there is a bug in the original documentation for code generation in Apiary.io (if you are using that) and the generated URIs at the moment that does not properly handle the escaping. You can turn on the Beta documentation, which does not have that issue.

Envision