I suggest you ...

Allow for elaboration of parameters in request/response

The current system lets you simulate an API call, but sometimes a mock call won't explain everything. Some parameters in the call might be required while other things aren't; others might only be required when a different parameter is included; there could be an option with five different choices and another with a boolean and you could want to explain what all the options do.

Thus I think there should be a place to describe the possible parameters and their options in the request and response, something like http://developers.dwolla.com/dev/docs/transactions/send

133 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…)
    Jeremy BrownJeremy Brown shared this idea  ·   ·  Admin →
    started  ·  ZZ responded  · 

    Updated information.

    You can already describe URI parameters in structured way with the new API Blueprint format. Refer to https://github.com/apiaryio/api-blueprint/blob/master/examples/7.%20Parameters.md for details.

    The new format is now default and URI parameters are properly rendered in the documentation.


    We are still working on description of http message–body properties (parameters). It is planned in the upcoming revision 1B of API Blueprint – as discussed in https://github.com/apiaryio/api-blueprint/issues/25

    14 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...
      • Jakub KorálJakub Korál commented  · 

        Actually ...

        This URI-template `/{file}{.extension}` would work as expected.

        When you expand it with extension='', you get the url `/file` without extension
        When you expand it with extension='json', you'll receive a `/file.json` url.

      • Tobias KopelkeTobias Kopelke commented  · 

        I'm not sure how to have optional static parts in my url
        These should work and return the same resource, just differently formatted:
        GET /service/{id}
        GET /service/{id}.{format}

        I'd write it like this
        GET /service/{id}[.{format}]
        in apiary I could write it like this-ish:
        GET /service/{id}.{?format}

        or do I need to create to API descriptions for the same resource?

      • Anonymous commented  · 

        I couldn't find a way to describe response parameters/objects attributes. Is this refering to the same issue.

      • Peter T. BrownPeter T. Brown commented  · 

        Just used up all the votes I could for this. Seems like a significant whole in the product design -- at least for us -- since we need to document the very critical aspect of our API: what data we return.

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi Ilja,

        this is because body parameters are not supported yet, but they are one of the top things on our TODO.

        In JSON, you can describe them using JSON schema, but we are not rendering them in documentation properly yet.

        Coming soon. Stay tuned!

        Lukas

      • Jakub KorálAdminJakub Korál (Developer, apiary.io) commented  · 

        Hi Christian,

        As Z has releases new parser version ( https://github.com/apiaryio/protagonist/releases ) today, parameters will be available in a week or so, hopefully not more.

        The documentation, that apiary provides right now, is not ready for Parameters unfortunately... But we are preparing new Documentation for a while, and these New Docs will be available to public very soon.

        If you are willing to participate in debugging closed-beta of New Docs (And yes! It works with Parameters), please drop a note at support@apiary.io - Thanks

      • ChristianChristian commented  · 

        Hi, has there been any movement on parameter description? This isn't ready to be a production-ready API document if it doesn't support explanation of parameters or return objects. Thanks

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Boris, please be assured that we are not ignoring this request, we are just thinking very hard about the solution as we don't want to compromise the simplicity of our format.

        We are also aware of the problems with onboarding into blueprint syntax, this is already in making and will hopefully help you all.

        Please stay tuned, you are not forgotten :)

      • Boris  StaalBoris Staal commented  · 

        Using hand-written markdown with custom structure is so uncomfortable. A lot of reasons for that: Markdown limitations, text overhead, the need to come up with structure, etc.

        As a fast solution you can add proposed structure to the default blueprint. At least we could all start with something, not "okay, how am I supposed to do that?". Seriously. At the first step you don't even know which header to use cause you are not aware of resulting documentation's CSS.

        At long term though you won't be able to ignore this requirement. I believe that sooner or later you'll have to come up with some kind of DSL to extend current blueprint syntax. So... +3 :)

      • MichalMichal commented  · 

        Well, I consider describing input/output attributes as a must-have and after hearing so much about Apiary, I'm quite surprised it's just not here :-/

        What I need is to describe each parameter, it's type (varchar, integer, boolean), give example values etc. Just the basics.

      • Machiel GroeneveldMachiel Groeneveld commented  · 

        I would like to describe each parameter and give example value(s). These example values can be used to generate a sample request url, the example code (e.g. curl) now has the raw uri template code in it, which is not usable straight away

      • Elan DubrofskyElan Dubrofsky commented  · 

        It would be really nice to be able to include descriptions of each parameter in a structured way, instead of having to come up with my own design using the overall markdown description.

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi,

        looking at dwolla, input parameter description in that way can be done already: just use markdown tables in resource description.

        We are thinking about ways to treat them like "variables". Our current approach is to use URI-templates-like syntax. Implementation is under way and is currently in beta stage. If you are interested, please vote / subscribe to this feedback http://apiary.uservoice.com/forums/120125-general/suggestions/2950994-support-path-parameters and we will let you know how things are moving.

        Does that solve your case?

        Regards,

        Lukas

      Feedback and Knowledge Base