By Z (zdne, z@apiary.io) on 27 Jan 2013
Apiary.io is growing and so are our users’ needs. We want to fuel the endless possibilities of where your API can go. We want to give you the best tools to design and maintain any REST-based API without boundaries or limits. Yet we must also guide newcomers who are just tapping the API World.
We are constantly improving our API Blueprint Format and I would like to share with you our thoughts on how it will evolve in the weeks to come.
We have decided to fully embrace Markdown for documenting your API. With the New API Blueprint Format your API documentation will be completely in pure Markdown excluding few extra MultiMarkdown features.
After all we are writing API documentation, not programming a backend in yet another domain specific language.
Markdown is supported by virtually every language or IDE in existence. There will be no need for additional syntax-highlighting plug-in to your favorite text editor. Also rendering will suddenly be ubiquitous from your Markdown aware text editor to GitHub GFM repositories.
With the New API Blueprint Format getting on board will be even easier. All in proper structural order, Markdown header specifying your endpoint followed by its discussion.
No more bloated API blueprints with lots repetition packed into one document. We will keep things DRY and introduce (more) modularity. Here is what is new in API Blueprint Format to deal with large, complex APIs:
New format will introduce support for discussing attributes including its type, default value and requirements.
While I understand and have nothing but utmost respect for “pragmatic REST” I want to encourage considering RESTful approach from the early beginnings. If Apiary would give you the right seamless tool to make real RESTful API with little extra effort would you opt to do so?
We will also deliver (or improve existing) support for multimedia, multiple request and response with improved schema support. This should be followed later by support for authentication an pagination.
As you can see there are big changes ahead. We will make sure to make things smooth for you and all our existing users.
In the next weeks I will be posting more details about the upcoming format changes including examples. In the mean time, if you’re excited what will the new format bring or just curious about the direction API Blueprint is heading, please head over to New API Blueprint Format. There you can vote for the new format and add your comments and wishes. Additionally you can contact me directly at z@apiary.io. I would love to hear from you.