17 comments

Add a comment…

Sign in

prestine

Your email address

Check!

invalid email

(thinking…)

Reset

or sign in with

• 
• 

UserVoice password

Forgot password?

Create a password

Your name

I agree to the terms of service

Signed in as (Sign out)

Close

Close

Post comment Submitting...

• Cagatay Kavukcuoglu commented  ·  March 21, 2013 8:42 a.m.  ·  Delete

  It should also be possible to include explanation for each alternative between the '+++++' separator and the request/response content.

• AdminZ (Admin, apiary.io) commented  ·  March 19, 2013 8:44 a.m.  ·  Delete

  @lobanovdy this week I will post a new blog post on New format rollout. Reasonable ETA would be mid-April. Since the format and its blueprint is OSS you can follow (and contribute) to its recent development directly in its GitHub repository https://github.com/apiaryio/blueprint-parser (check out branches).

  In the New Format multiple responses would be like

  # GET /resource

  + Request (application/json)

  { ... }

  + Response 200 (application/json)
  
  { ... }

  + Response 404 (text/plain)

  ...

  Mind that you can already describe multiple even with the Legacy Format: http://support.apiary.io/knowledgebase/articles/117119-handling-multiple-actions-on-a-single-resource

• lobanovdy commented  ·  March 18, 2013 2:56 a.m.  ·  Delete

  When can we expect to see new format in action? I'm excited about possibility to declare several responses for 1 request, because it's quite common if you have 1 request and at least 2 possible responses (ok and fail).

• AdminZ (Admin, apiary.io) commented  ·  March 5, 2013 11:51 a.m.  ·  Delete

  @paul Thank you for input. You are indeed right, the `@` sign is rather alien to Markdown. Recently we have changed it to `+` sign which also represent a list item thus it plays nicely with Markdown.

  Refer to https://github.com/apiaryio/blueprint-parser/blob/zdne/format1A/doc/APIBlueprintSpecification.md for the latest specs (and examples).

  Please drop me a note (this forum, email or GitHub) should you have any further comments. Much appreciated!

• Paul Eipper commented  ·  March 5, 2013 11:28 a.m.  ·  Delete

  The current proposal marks parameters with @, but what is the rationale? If you want to keep close to Markdown, you could use the backtick quotes, which already are parsed as literals. Example: https://gist.github.com/lkraider/5093191

• AdminZ (Admin, apiary.io) commented  ·  February 13, 2013 6:49 a.m.  ·  Delete

  Bellow you can find list of related ideas that will (or might) be addressed by New API Blueprint Format:

  [Support application/x-www-form-urlencoded input parameters]
  (http://support.apiary.io/forums/120125-general/suggestions/3041207-support-application-x-www-form-urlencoded-input-pa)

  [Allow for elaboration of parameters in request/response]
  (http://support.apiary.io/forums/120125-general/suggestions/3089236-allow-for-elaboration-of-parameters-in-request-res)

  [Support http authentication]
  (http://support.apiary.io/forums/120125-general/suggestions/2966904-support-http-authentication)

  [Store API definitions in more than one file, enable linking]
  (http://support.apiary.io/forums/120125-general/suggestions/2873414-store-api-definitions-in-more-than-one-file-enabl)

  [Support OAuth authentication methods]
  (http://support.apiary.io/forums/120125-general/suggestions/2981979-support-oauth-authentication-methods)

  [Support multiple content formats]
  (http://support.apiary.io/forums/120125-general/suggestions/3010290-support-multiple-content-formats)

  [Use json-schema to describe data types]
  (http://support.apiary.io/forums/120125-general/suggestions/3283512-use-json-schema-to-describe-data-types)

  [Global default request and response headers w/ override mechanism.]
  (http://support.apiary.io/forums/120125-general/suggestions/3317694-global-default-request-and-response-headers-w-ove)

  [Reusable output components]
  (http://support.apiary.io/forums/120125-general/suggestions/3051858-reusable-output-components)

  [Add comments and block comments in the blueprint syntax, ignored by apiary]
  (http://support.apiary.io/forums/120125-general/suggestions/3048618-add-comments-and-block-comments-in-the-blueprint-s)

  [Add a way to specify default parameters for URI templates]
  (http://support.apiary.io/forums/120125-general/suggestions/3096640-add-a-way-to-specify-default-parameters-for-uri-te)

  Following ideas weren't reviewed yet. Please vote on the respective ideas if you would like to support it.

  [Match on request headers]
  (http://support.apiary.io/forums/120125-general/suggestions/3264498-match-on-request-headers)

  [Support for API with callbacks]
  (http://support.apiary.io/forums/120125-general/suggestions/3264958-support-for-api-with-callbacks)

  [Support different scopes for API documentation]
  (http://support.apiary.io/forums/120125-general/suggestions/3278959-support-different-scopes-for-api-documentation)

• AdminZ (Admin, apiary.io) commented  ·  February 13, 2013 1:35 a.m.  ·  Delete

  Note that this suggestion will be covered by upcoming API Blueprint Format update. Please refer to http://support.apiary.io/forums/120125-general/suggestions/2970802-new-api-blueprint-format.

• AdminZ (Admin, apiary.io) commented  ·  February 13, 2013 1:11 a.m.  ·  Delete

  Note that this suggestion is one of the priority features of the upcoming API Blueprint Format update. Please refer to http://support.apiary.io/forums/120125-general/suggestions/2970802-new-api-blueprint-format.

• AdminZ (Admin, apiary.io) commented  ·  February 13, 2013 1:09 a.m.  ·  Delete

  Note that this suggestion might be covered by upcoming API Blueprint Format update. Please refer to http://support.apiary.io/forums/120125-general/suggestions/2970802-new-api-blueprint-format.

• AdminZ (Admin, apiary.io) commented  ·  February 5, 2013 6:46 a.m.  ·  Delete

  Dear Stan,

  For the time being I would suggest you to discuss multiple responses in general endpoint discussion using markdown formatting of your liking.

  For the future I am currently working on new blueprint format, which may bring additional way to discuss responses. Please see http://support.apiary.io/forums/120125-general/suggestions/2970802-new-api-blueprint-format and feel free to vote or comment there.

  Thank you.

• Martin Wawrusch commented  ·  October 22, 2012 9:35 a.m.  ·  Delete

  And because we can't edit our comments here let me just throw in json schema... :-)

• Martin Wawrusch commented  ·  October 22, 2012 9:34 a.m.  ·  Delete

  This is so important and goes actually beyond just output, it is input as well. Basically you have an object model that is returned from the api, which might even be constrained by the authenticated scope the user is in (we return more info the higher the user's scope is)

• Andrei Neculau commented  ·  September 28, 2012 6:59 a.m.  ·  Delete

  Maybe this is really needed, but I think there is a request that supersedes this request: DRY.

  And yes, one way would be to have variables.
  The other way, for "KISS Apiary"s sake, is for those that want complex blueprints, to use tools to build their apiary blueprint.

  PS: speaking from experience, trying to fulfill all requests leads to a messy outcome. Responsibilities needs to be divided. A tool builds the blueprint, a service uses a blueprint for X, Y, Z. Guy Kawasaki says it better and funnier: http://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=2&cad=rja&ved=0CCYQtwIwAQ&url=http%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DjSlwuafyUUo&ei=HK1lULmVMsXHsgb_nYGIBw&usg=AFQjCNFWjAsxICT03XCA8EhVwn9iGRX_bw&sig2=c8oCYsvRvn8TjFBRS3W-Qg

• AdminJakub Nesetril (CEO, apiary.io) commented  ·  August 22, 2012 1:56 p.m.  ·  Delete

  Andrei, thanks for the comments! We're still considering how much to bend the Blueprint format around Markdown. I'm inclined to leave the core blueprint format close to unchanged, but allow including it in more verbose markdown context OPTIONALLY for users who wish to write more markdown-oriented documentation.

  We're inclined to opensource the grammar, and the parser/generator as part of the revamp, which should help migrate your blueprint-generating tools swiftly.

  In any way, we'll update this well ahead of time so that we give our users time to migrate.

• Andrei Neculau commented  ·  August 22, 2012 1:26 p.m.  ·  Delete

  Just my 2 penny:
  - the > and < markers are rather natural (at least to me) to mark IN & OUT (shell?!)
  - I prefer this type of natural, vs the Markdown natural. Afterall, I'm still a guy that deals with curl, APIs, etc, not writing an API book in Markdown.. Markdown for descriptions is very nice and natural though.
  - I also don't see high chances of having the payload start with these markers. But in case it happens, maybe you can enforce it to be escaped or have a payload end-marker, such as

  URL
  > header
  data
  data
  >>>
  < 200
  < header
  data
  data
  <<<

  - last but not least: i vote -100 for the any gain from making it more verbose. Making it maybe a bit more fluent, yes - would be nice, though I find it extremely natural as it is right now. But more verbose?!

  With all that being said, knock yourself out, guys =) Why?
  1. I put my trust in you to reach a swift conclusion
  2. I will always end up generating the Apiary blueprint from my format, thus..

• AdminApiary (Admin, apiary.io) commented  ·  July 2, 2012 8:19 a.m.  ·  Delete

  Indeed. More details are coming, for now:

  - strict Markdown superset
  - more verbose

  So probably doing away with the structure of

  URL
  > incoming headers
  incoming data
  < status
  < outgoing headers
  outgoing data

  in favor of something like

  ## Resource: GET /example
  > description
  > description
  - Headers In:
  - Data In:
  { some json }
  - Headers Out:
  - Data Out:

  It's a rough idea for now. I'll post example when we have more.

• Andrei Neculau commented  ·  July 2, 2012 7:59 a.m.  ·  Delete

  Would be nice even to get a headsup on whatever syntax ideas you have already (~thinking out loud)