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. Multiple APIs in one Github repository

    It would be great to have multiple API files stored in 1 Github Repository. We have internal APIs that are documented separately, however we don't wanna have a separate repository in Github for each API.

    113 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…)
      started  ·  Lukas LinhartLukas Linhart responded

      We are working on this one. Stay tuned, and let us know here if you’d be willing to betatest.

    • 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…)
        started  ·  Lukas LinhartLukas Linhart responded

        We are offering embedding as part of our Apiary for Companies plan. Please contact support@apiary.io if you want to try it out.

        That said, we are going to offer simpler & cheaper possibility by using CNAME. This is planned to be available this year.

      • Support http authentication

        Provide some way to indicate the required authentication (if any) for any given call. We use a combination of user credentials and api keys for our http basic auth, and would really like to see some way to support http authentication as part of the documentation and mockups. Also for Oauth scenarios perhaps?

        248 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…)
          started  ·  Lukas LinhartLukas Linhart responded

          We are working on http auth support as part of our blueprint overhaul.

        • allow exporting formatted document to pdf, doc, rtf, et al.

          Having online documentation is great for developers to work with each other but it would also be good to be able to export the document to include in other system documentation or to be able to email it to 3rd parties.

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

            Apiary now has a print stylesheet for the generated Docs.

            It uses numbering + table of contents and displays the examples with language you have selected in the language-dropdown.

            The preferred way of sharing the documentation with 3rd-parties is through People settings (add viewers). However printing now looks great.

            Feel free to comment.

          • Support versioned documentation through git branches/tags

            Developers who use a branching/tagging conventions in git (such as GitFlow: http://nvie.com/posts/a-successful-git-branching-model ) would appreciate this being reflected in apiary.

            In this way the documentation for the current stable release of an api might be drawn from the repository's master branch, while previous versions would be available at tags, and ongoing work towards the next release could be viewed and discussed at a develop branch.

            If the mock api were similarly configurable it'd be extra brilliant.

            110 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…)
              started  ·  Lukas LinhartLukas Linhart responded

              We are working on the initial workflow support using git branches.

            • Add back print stylesheet to new documentation

              There was a quite nice (at least working) stylesheet for printing the "old" documentation page...
              With the new documentation styles, printing can't be done! Please add the stylesheet back :)

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

                Preliminary stylesheets are available.

                Not closing this one, though, as we plan do to significant improvements on them.

              • Define global headers for all requests/resources

                I found that I have to write request/resource headers on each of them even if I have some globals. So I think that defining globals will be great.
                For example:

                HOST: https://api.example.com
                > Accept: application/json
                > Accept-Language: cs-CZ,cs;q=0.8
                < Content-Type: application/json; charset=utf-8

                --- Gorgeous API ---

                9 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…)
                • provide API to upload blueprint file

                  We are hosting our blueprint file in a private SCM repository.

                  I wonder how we can upload the blueprint file once we pushed a change.

                  9 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…)
                  • 75 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…)
                      started  ·  Lukas LinhartLukas Linhart responded

                      We have started to work on some OAuth2 support and testing it with some customers.

                      Current status is “very alpha”; you can only mark the whole API as being authenticated and we do not provide any support for mock server yet.

                    • Store API definitions in more than one file, enable linking

                      With just 4 api calls the file is already getting pretty big, I would welcome being able to organize the API blueprints into subdirectories somehow.

                      Also being able to identify an API call and link to it both from outside (as in: use THIS api call to do what ou wish) and inside (this api call is the same as THIS except for ...)

                      86 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…)
                        started  ·  Lukas LinhartLukas Linhart responded

                        Undocumented pre-alpha is live, but not all in-product edges are fine-tuned properly.

                        Please let us know (e-mail to support@apiary.io) if you want to use this feature, we will give you a howto.

                      • Support Intradocument links in markdown

                        It would be very convenient to have intra-document links in the blueprint.

                        The syntax {#Header} is sometimes used to add names to headers in the rendered html. Source: https://meta.stackexchange.com/questions/29063/why-is-a-special-character-in-markdown

                        Alternatively, please render a name, id, or href on headers from markdown.

                        As examples:

                        Bitbucket renders it as an id; `# Hello world` becoming `<h1 id="markdown-header-hello-world">`.

                        Github renders it as an href: `# Hello world` becoming `<h1 href="#hello-world">`

                        16 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…)
                        • display all attributes for a Data Structure in the Example pane

                          Currently all I get are the entries in the top level object returned, my payloads contain a lot of nested objects which mean my options are either:
                          1. Repeat the information in Data Structures elsewhere / reformat so it is included in the documentation
                          2. Not have a data dictionary displayed to uses which greatly reduces understandability.

                          As it stands I waste my time documenting my data dictionary in the Data Structures section as it's not displayed anywhere.

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

                            MSON is still in beta, and we are working on displaying all its’ facets, including nested objects and Arrays.

                            Feel free to describe them, they are going to show up over time.

                          • Make comments more visible and add notifications

                            Comments are currently quite well hidden. You have to expand the endpoint, and then click the Comments tab to see them at all.

                            More: there's currently no email notification of new comments, even if they're replies to something I posted myself. This makes it awkward to iterate with clients on an API design; you have to send them "I've replied to your questions" emails all the time.

                            44 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…)
                            • Support HATEOAS (e.g., support links in responses to navigate to other resources)

                              Our API uses http links to navigate between resources. You can start from a single defined resource and then navigate down to the other resources in the API and their related resources.

                              Chrome's POSTMAN does it fairly well, but it would be great to embed such a feature in an API blueprint and I haven't seen support for this in any of the other API tools.

                              13 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…)
                              • 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…)
                                  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

                                • Shared API blueprint templates to bootstrap new projects

                                  I apologize in advance if this is something I was just unable to find. From the products page I see the feature for bootstrapping new projects. Is there an ability to either use or create a base/template document that is used whenever creating a new API? Is the Notes example currently the only one available?

                                  Thank you. Looking forward to learning much more about apiary!

                                  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 →
                                    started  ·  Lukas LinhartLukas Linhart responded

                                    It is so. We are now actively working on changing that documentation: extending the documentation and better sharing of the real-world blueprints and their organisation into the galleries.

                                  • Allow to describe a response in plain Markdown

                                    I'm using the new *X-1A* syntax which supports multiple responses, though only when the response code is different (could not manage to have responses with the same response code; please let me know how to accomplish this).

                                    Since there are multiple response going one after another, in the rendered examples view it is difficult for an API user (not API developer) to quickly understand the difference between each responses since they all refer to the same request resource. It would be nice to optionally allow to describe each response in plain Markdown syntax.

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

                                      This is possible to do in the new format, but we are not displaying this properly in the old documentation.

                                      We certainly plan to fix this and I’ll keep you posted once it’s live.

                                    • Hypermedia APIs

                                      Have you guys done any work on hypermedia APIs? Specifically I'm implementing an API that uses HAL (json+hal) with features such as links to other resources and 'profile' properties. These hypermedia formats potentially open up a way to automate some pretty sophisticated documentation capabilities. I'm not sure how this factors into what kinds of capabilities you could support in the future and it's probably not widely used yet but it's something to think about going forward. There are other competing formats like collection+json, jsonapi.org, to consider as well.

                                      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 →
                                      • Improve the input form for Try It

                                        Try It is great - but editing the inputs is painful.
                                        Ideally you'd auto-generate a web form where I can enter a value for each input parameter (and if you show me the description and/or json-validations next to each, you get bonus points). Second-best would be to let me structure XML or JSON input in a textbox.
                                        (yes, I'm comparing to swagger, sorry)

                                        8 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…)
                                          started  ·  Lukas LinhartLukas Linhart responded

                                          The new console (in the still-beta "New Documentation) generates a form you can use to input the URL parameters.

                                          This will be available for the payloads as well once the payload description support will be available in Apiary.

                                        • Test suite from blueprint

                                          Provide a way to execute test suite.

                                          Test suite will go through defined resources execute according requests against given server. Results will be then compared with blueprint and pass/fail status will be shown.

                                          17 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 →
                                          ← Previous 1
                                          • Don't see your idea?

                                          General

                                          Feedback and Knowledge Base