I suggest you ...

New API Blueprint Format

We're discussing migrating the API Blueprint format from line-oriented DSL with embedded Markdown to a strict Markdown super-set.

We still want to keep (and even improve) the simplicity and readability of the format. Here are some of the intended advantages:

The first motivation is to make the documentation more text/prose/use-case focused and less URL/method focused.

The second motivation is to better fit into existing ecosystems (all Markdown syntax highlighters would do a good job of highlighting the blueprint).

Third - we feel we'll have more room to grow our feature-set (multiple responses per resource, defined parameters / authentication style etc.)

If this transition ever happens, we will warn all users upfront, give them time to prepare, migrate all their existing blueprints automatically and offer assistance with any migration issues.

If you'd like to discuss the API format changes with us, please vote for this topic so that you can be notified of all updates when we post the new format details.

Regards,

Jakub

103 votes
Vote
Sign in
Check!
(thinking…)
Reset
or sign in with
  • facebook
  • google
    Password icon
    I agree to the terms of service
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    ApiaryAdminApiary (Admin, apiary.io) shared this idea  ·   ·  Admin →
    Anonymous shared a merged idea: Blueprint Objects  ·   · 
    Cagatay KavukcuogluCagatay Kavukcuoglu shared a merged idea: Additional request headers when defining multiple actions for a single resource  ·   · 
    Libor KramolišLibor Kramoliš shared a merged idea: Add support to describe more than one request/response per a method.  ·   · 
    An PhuAn Phu shared a merged idea: global default request and response headers w/ override mechanism.  ·   · 
    Lukas LinhartAdminLukas Linhart (Admin, apiary.io) shared a merged idea: Add a way to specify default parameters for URI templates  ·   · 
    Petr BelaPetr Bela shared a merged idea: Reusable output components  ·   · 
    completed  ·  ZZ responded  · 

    As of now the New API Blueprint is the default format used in Apiary.

    Find more about the New API Blueprint in this blog post: http://blog.apiary.io/2013/10/02/New-API-Blueprint-available and its website: http://apiblueprint.org

    To directly dive into the new format create a new API in Apiary or head over to the API Blueprint Tutorial: http://apiary.io/blueprint

    Should you have any question using the new format visit (and ask at) Stack Overflow: http://stackoverflow.com/questions/tagged/apiblueprint

    In the case of suggestions for format change or feature requests visit API Blueprint Milestones at: https://github.com/apiaryio/api-blueprint/issues/milestones

    You can also let us know what do you think using the Apiary support channels or email me directly at z@apiary.io

    – Z.

    19 comments

    Sign in
    Check!
    (thinking…)
    Reset
    or sign in with
    • facebook
    • google
      Password icon
      I agree to the terms of service
      Signed in as (Sign out)
      Submitting...

      Feedback and Knowledge Base