By Lukas Linhart (almadcz, lukas@apiary.io) on 05 Feb 2013
I’m excited to to announce that I have finally completed migration to our new parser. It is more robust, more formal, totally open-source and will serve as a base for further improvements of our syntax.
With that, Apiary Blueprint Format is now defined as a proper grammar. Both grammar and javascript parser (works both in browser and in node.js) are open-source and available on github. It is based on PEG.js and I’d like to thank its author, David Majda, for writing it and also contributing enormously to Apiary blueprint grammar.
We have worked hard to maintain backward compatibility. However, there are some areas where the behavior of the old parser was undefined and while it is valid with new parser, it may lead to unexpected results. Therefore, we encourage you to take a look at your documentation, verify everything is OK and let us know if you need help.
The main change comes with header and payload definition. In some places, the old parser incorrectly accepted empty newlines inside headers or payload. This is not allowed as empty line indicates “end of the resource”. If you need to have empty lines inside your payload, you may take advantage of our new “heredoc” syntax:
POST /resource
> Content-Type: text/css
<<<EOT
body {color: purple}
.content {text: pink}
EOT
< 200
< Content-Type: application/xml
<<<EOT
<result>
<ok/>
</result>
EOT
EOT may any alphanumeric sequence of your choice.
The new parser will allow us to be more agile in the evolution of our format. The grammar now also serves as a formal definition of our language.
Many people from the open-source community asked us how they can integrate with our format, whether that is automatic generation of frisby.js tests or scaffolding of Ruby apps. We love open-source, so we embrace this collaboration wholeheartly. Hopefully, the new parser should make this easier for us all.
To be future-proof, you should use a generator for your language and use our grammar directly. Also, don’t forget to subscribe to our mailing list, where you can find information about new releases and important changes.
Created something cool with apiary? Let us know! Mention us on twitter or write me to lukas@apiary.io.
We’ll be glad to hear from you!