General

I suggest you ...

You've used all your votes and won't be able to post a new idea, but you can still search and comment on existing ideas.

There are two ways to get more votes:

  • When an admin closes an idea you've voted on, you'll get your votes back from that idea.
  • You can remove your votes from an open idea you support.
  • To see ideas you have already voted on, select the "My feedback" filter and select "My open ideas".
(thinking…)

Enter your idea and we'll search to see if someone has already suggested it.

If a similar idea already exists, you can support and comment on it.

If it doesn't exist, you can post your idea so others can support it.

Enter your idea and we'll search to see if someone has already suggested it.

  1. Allow us to read other API's blueprint

    Since I'm new to apiary syntax I usually google for other people's docs so I can see how they are using apiary in real world, but when I found something interesting, I can't see how it was done, because I can only see the final doc, not the blueprint.

    It would be great to be able to also read the blueprint, not only the rendered doc.

    10 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…)
      completed  ·  Lukas LinhartLukas Linhart responded

      The API Blueprint link is shown for documentations that enable “Public Blueprint” in their settings.

    • Support query parameters with dot notation

      It seems that dot notated query parameters are not supported in the new beta version console.

      ie /resources{?page.number}

      The complete definition of this results in showing the following message when you go to the console to craft demo request

      ---
      We are sorry, but it seems that the URI template is invalid. Please contact support@apiary.io, we'll help you sort it out.

      Error: Invalid Variable Name "page.number" in "{?page.number}"
      ---

      Apologies if this has been raised previously, it's not the easiest of terms to search for.

      2 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…)
        completed  ·  Lukas LinhartLukas Linhart responded

        When using the “New” blueprint (FORMA: 1A) and the “new documentation” (have to be enabled in settings), you can now include dots into your URLs under two conditions:

        1) dot has to be percent-encodd (as in page%2Enumber)
        2) The variable has to be described in the Parameters section.

        Otherwise, it should work and be encoded properly.

      • Delete an api

        The ability to the remove an unwanted api

        2 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…)
          completed  ·  Lukas LinhartLukas Linhart responded

          Under settings, look for “Remove API Blueprint” where you can delete the API if its not your last one.

        • Allow groups to be nested

          When grouping resources, allow subgroups. They should also be rendered as subsection in TOC.

          See github api doc for an example.

          11 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…)
            completed  ·  Lukas LinhartLukas Linhart responded

            This can now be achieved using Resource Groups and Resources using the new blueprint format.

          • Validate schema against JSON Schema Draft v4

            As the support team said the JSON Schema Draft v3 is assumed at the moment. That makes my API documentation complicated to use for the end-users because the validator says "JSON schema is not valid! invalid type: array (expected boolean) at path "/required"". I would like to use the draft v4 as a default schema or have a chance to set the $schema at the root of my schema with http://json-schema.org/draft-04/schema# as a value. Just to let the validator know which schema I would like to use.

            55 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…)
            • Embeddable code examples

              Hi,

              it would be cool to have the generated code examples embeddable.
              So they could be reused in other documentations

              2 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…)
              • forgot a ,

                You forgot a , in your Blueprint template:

                { "url": "/shopping-cart/1" "product":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 }

                1 vote
                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…)
                • Allow user to switch between mock and real API

                  For documentation purposes, admin may want to show real API in examples / try it console.

                  Also provide switch for viewer to toggle between those modes when playing with API.

                  3 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…)
                    completed  ·  Lukas LinhartLukas Linhart responded

                    This is done in the “New Documentation” that can be enabled in the Settings.

                    It will be the default in a short time.

                  • Clarification in your Blueprint doc

                    It says

                    "Note: Make sure to include a space between the --- characters and the title text."

                    But you are showing -- Shopping Cart Resources --

                    Should it be -- or ---?

                    1 vote
                    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…)

                      Johnny,

                      there is - for section heading and -- for the whole API title.

                      You’re right that the documentation had a typo in it, which has been fixed.

                      Thank you,

                      Jakub

                    • Link documentation to another Git repo for collaboration

                      Developers should be able to fork the documentation on Github and make changes directly and make pull requests.

                      For this to work you have to make an own Github repo for the documentation so they can fork it (since I don't want my application code to be accessibly for the users).

                      1 vote
                      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…)
                        completed  ·  Lukas LinhartLukas Linhart responded

                        Linking with github and working there works exactly as you described. Just go to settings and link your blueprint with github repository.

                      • One place to select language

                        Cool that you can have your examples in different langs!

                        However, it seems that I am forced to select language for each example. Would be great if there was a memory for the selection so I just need to select it once so if I select python it will change all the examples to python and also remember it next time I log in.

                        I think it's good like it is right now that you have that selection list in the example, that is not a global one, since everything should be in place (Don't Let Me Think).

                        So just…

                        2 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…)
                          1 comment  ·  Admin →
                        • 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.)

                          95 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…)
                            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.

                          • Support multiple content formats

                            Our API allows switching response and PUT/POST content between JSON and XML, based on Accept headers and/or a query parameter. It's awkward to document both formats. Currently, I am duplicating the docs for every call.

                            It would be ideal to be able to put both formats in the request/response sample data in the blueprint, maybe based on the Accept or Content-Type header values, and then switch between them, or have a global switch that uses on or the other based on a reader's choice.

                            See the Shopify API docs for an example (the Format dropdown at upper right):

                            http://api.shopify.com/index.html

                            26 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…)
                              completed  ·  Jakub KorálJakub Korál responded

                              Apiary mock server now supports basic server-side Content Negotiation.

                              If your request contains Accept (or Accept-Charset, Accept-Language, Accept-Encoding) header(s), Apiary will count “quality” of each available Response and return the finest one.

                            • Allow multi-line responses

                              At the moment you cannot enter a response that spans several lines. For XML responses this makes it hard to write out a readable response that is properly formatted.

                              1 vote
                              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…)
                              • it is really good if you provide the support for XML api also

                                Now, Apiary is giving support only for JSON. Please provide the support for XML also. .Net Web api is supporting xml and JSON for the same object. so, we can demonstrate to our clients with apiary easily.

                                3 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…)
                                • wordwrapping

                                  This seems like a very simple tweak that could go a long way. Obviously making it an optional ui element.

                                  1 vote
                                  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…)
                                    1 comment  ·  Admin →
                                    completed  ·  Lukas LinhartLukas Linhart responded

                                    We don’t like to clutter our UI, but there is a shortcut for that :) Hit ctrl+shift+w . Fore more shortcuts, try ctrl/cmd+alt+h, we are going to provide a hint for that.

                                  • customize the apiary console drop-down menu

                                    I want to customize the apiary console's drop-down menu. Here is my use-acases

                                    I have added the `HOST` field in apiary blueprint which is a url of a staging server. In console, by default, the drop-down menu shows `production` name for this url.

                                    1). Is it possible change the `production` in console drop-down menu to `staging` ?

                                    2). Is it possible to remove the "Debugging Proxy" from drop-down menu ?

                                    1 vote
                                    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…)
                                    • Share multiple APIs to people

                                      I have created number of APIs , and i need to share each of these API to other people.
                                      Right now, i need to share each API separately.

                                      Is there nay way to share multiple APIs at once with a people ?

                                      OR

                                      can a collection can be made of number of apis, and that collection can be shared with people.

                                      OR

                                      1 vote
                                      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…)
                                        1 comment  ·  Admin →
                                        completed  ·  Lukas LinhartLukas Linhart responded

                                        Apiary for Temas provide you tools to bulk-share with other people in your team, and we plan to enhance it to have more fine-grained group-based sharing tools.

                                      • restricted traffic inspector data

                                        Give the ability to generate a hashed url on the fly to give out and restrict public access to the traffic inspector data from that url so the general public doesn't see sensitive data such as passwords or auth tokens.

                                        3 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…)
                                          1 comment  ·  Admin →
                                          completed  ·  Lukas LinhartLukas Linhart responded

                                          Every user has it’s own hashed url that is not shared with anyone else.

                                        • External editor support

                                          I would love to be able to use the Apiary platform to host docs/proxies/etc., but don't like the idea of having to write my markdown in a web-based editor. I would love to be able to easily upload externally edited files.

                                          1 vote
                                          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…)
                                          • Don't see your idea?

                                          General

                                          Feedback and Knowledge Base