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 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 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 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

        • 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.

          • History and Version Control

            The platform is missing change history and an ability to save draft versions.

            What happens if someone deletes everything by accident?

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

              We do track revisions internally, but we are yet to release proper API and UI for that. It is fairly high on our list, though.

            • 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.

              • 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.

                • Allow multiple HOST servers (staging, QA, prod, etc)

                  Currently one can define a single HOST endpoint that will be displayed in the right-hand column when viewing an API. It would be great if we could create multiple HOST definitions for different environments and name them descriptively.

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

                    We are not sure if multiple HOST headers are the right solution, but we definitely want to provide a way to use Apiary against staging environments.

                  • 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.

                    • 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.

                      • Add an activity feed for blueprints so you can track what's been happening.

                        An activity feed (like Trello for example) of all the actions that have taken place on the API (edits, deletions, comments etc). This would add a massive amount of value around the collaboration on a Blueprint.

                        73 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 templating in responses

                          Provide a way to populate some parts of response with "variables".

                          Some ideas:

                          * Provide "api base" that is corresponds to generated mock server URI
                          * Provide same variables that are specified in templated URI

                          62 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…)
                            planned  ·  4 comments  ·  Admin →
                          • 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…)
                            • Generate documentation info from JSON Schema

                              When JSON schema is provided, inject documentation (in form of table?) into related resource.

                              41 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…)
                                planned  ·  7 comments  ·  Admin →
                              • add JSON formatting.

                                When entering JSON format data I take the junk spit out of my actual API implementation and enter in the blueprint. It's not normally pretty printed. You could use JSON Lint.

                                https://github.com/zaach/jsonlint

                                40 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…)
                                  planned  ·  4 comments  ·  Admin →
                                • Organize and manage big lists of APIs better, use groups of APIs.

                                  The way in which the APIs are organized should allow from groups of APIs to be set. If you have dozens or hundreds of APIs you want to be able to group them in functional clusters. As it is today, they are all below a common root node, making them hard to manage if you have too many.

                                  The current way to list your APIs in the top dropdown menu is easy enough if you have a couple of APIs, but cumbersome if you have dozens of APIs.

                                  This is critical for the insertion of big sets of APIs.

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

                                    Agreed. As we are starting to have heavy users, we’ll have to provide such functionality.

                                  • Allow describing of data model and reference description in API definition

                                    I want to be able to describe my data model and then tell my various routes that they either expect that model passed in and/or promise to return that model. That way I don't have to describe my model once for POST and again for GET and again for PUT etc...

                                    36 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…)
                                      planned  ·  ZZ responded

                                      Dear Christopher, this is definitely planned for an upcoming revision of New API Blueprint Format (most likely 1B).

                                      I plan to introduce “data dictionary” and payload / asset referencing that should address these needs.

                                      Than you for your input, much appreciated!

                                    • Add GitLab support, similar to GitHub

                                      GitLab ist a cloud- or self-hosted code colaboration platform.

                                      35 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 generic git repositories

                                        We'd like to store the blueprint in bitbucket, it would be nice if there was support for generic git repositories for that reason.

                                        Thanks!

                                        35 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…)
                                        • JSON validation

                                          Display warning if example JSON in request/response is not well-formed.

                                          32 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…)
                                          ← Previous 1 3 4 5 8 9
                                          • Don't see your idea?

                                          General

                                          Feedback and Knowledge Base