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. Support customizing the apiary file saved to Github

    It would be nice to allow some customizations to the file saved into Github. Currently it's saved as "apiary.apib" at the root of the repo, but it would be nice to be able to change the name and/or location of that file.

    This feature would be useful if there are more than one apiary documents that need to be saved into the repo.

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

      That is definitely planned as overhauling the whole github experience is near.

    • Possible to use Response status subcodes?

      It seems that subcodes are currently not supported by Apiary or API Blueprint, at least if you want to use the blueprint to mock out your API with http status subcodes.

      For example, a response like:

      + Response 403 (application/json)

      + Body

      {
      "message": "Forbidden"
      }

      ..works fine when I call my API and include the parameter Prefer:status=403. However, if I change the response code to 403-001, Apiary cannot find the response to send back. For example:

      + Response 403-001 (application/json)

      + Body

      {
      "message": "Forbidden"
      }

      Is this a limitation in Apiary specifically, or in API Blueprint in general?

      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…)
        under review  ·  1 comment  ·  Admin →
      • 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…)
        • Allow for versions of the API

          We're rolling out a new version of our API and would love to have a way to have documentation for v1 and v2 available.

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

            • "pending approval" comments

              Give the ability to approve public comments before they are published to the api doc instead of letting the general public post a comment without manual approval.

              4 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…)
              • debug passthrough proxy

                You have a great debugging tool (traffic inspector) it would be really cool to use the debug url as a passthrough to the production url. That way the traffic inspector can be used to debug stageful issues using production endpoints. Currently, it can only be used to test stateless things like request/response structure.

                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 →
                • Support n-depth Groups

                  The Groups are great, but they don't go far enough for use cases where I have 2+ levels of resources I want to group together. In my API there are logically related resources that I'd love to bucket into a group but am unable to. Ideally this structure would be possible:

                  # Group
                  ## Resource 1
                  ## Resource 2
                  # Sub-Group
                  ## Resource 3
                  ## Resource 4

                  4 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…)
                    under review  ·  Lukas LinhartLukas Linhart responded

                    Thanks for the submission. We are thinking how to make structuring of the larger blueprint better, and this is one of the options.

                  • Respond with an error when a request is invalid, based on JSON Schema.

                    It would be nice if Apiary responded with a 400 Bad Request if the request body did not validate against a given JSON Schema. The response body should contain the validation error message/instructions.

                    19 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…)
                    • Let docs be private/public per-section in markdown syntax to avoid copying/pasting from private to public

                      Maintaining an internal copy of docs, and then copying docs over to the public page as features are released, is a pain and leads to maintaining two copies of some of the doc sections, which gets out of date quickly. Being able to flag sections as private, and have a private users view both public and private sections, would be huge for us.

                      5 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 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…)
                          under review  ·  1 comment  ·  Admin →
                        • Enable global search in new API blueprint

                          Our users really liked the ability to quickly search the whole API blueprint, including JSON, in the old format. In the new three-column format this isn't possible because the JSON for only one entry is ever visible. When multiple text files are enable, search will become even more important. Please add!

                          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…)
                            1 comment  ·  Admin →
                          • Allow a commit message prefix into Github

                            We currently try to prefix all our Blueprint changes with "Apiary - " so that it's easier to distinguish documentation changes vs code changes using the commit comment. It would be nice to have a feature that automatically adds a custom prefix to Blueprint commits. This would promote consistency across all changes amongst our team members.

                            4 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…)
                            • Create webhooks for use with other collaboration tools such as Flowdock or Slack.

                              It would be great if you guys had webhooks that would post to collaboration tools such as Flowdock, Slack, Asana, or Basecamp. This would be particularly useful for comments so that team members can see when comments are posted and respond in a timely manner.

                              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…)
                                1 comment  ·  Admin →
                              • Validate parameters in the mock server

                                It would be nice if the mock server could validate the resources parameters.

                                Example:

                                ```
                                ## Notes Collection [/notes{?query}]

                                + Parameters
                                + query (required, string, `Hello World`) ... some example.
                                ```

                                The `query` parameter is required in the API Blueprint. Requesting `/notes` without the query parameter works fine with the current mock server. This could instead return a 400 since it is a bad request.

                                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 API validation with generated resource id(NoSQL)

                                  It would be great to allow URI parameters to be set based on previous response, this necessary when I need to test API with NoSQL backend where ObjectID is used instead of integer.

                                  For example, when I run dredd test with following definition:

                                  https://gist.github.com/elmariofredo/f89c54c126680dad6136

                                  it won't pass as id 53c4f8314d84769d9f61ec87 doesn't exists at the time of testing.

                                  It would be great to set id param as pointer to create response and it's resulted id.

                                  p.s. your gist like example in http://apiary.io/blueprint is bit cheating with integer/string id, so it would be great if one can really create working github gist…

                                  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…)
                                  • Hyperlinks that end with ) in Blueprint

                                    I'm trying to link to this wikipedia page and it won't work because it ends with )
                                    Example:
                                    [Normal Saline](http://en.wikipedia.org/wiki/Saline_(medicine))

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

                                      This is the limitation of the underlying reference Markdown parser. We’ll see what you can do.

                                      Meanwhile (and yes, it’s inconvenient), you can encode parenthesis as %28 and %29, as it’s done in URL address anyways. I understand it’s inconvenient,

                                    • Allow to share request permalink traffic

                                      It would be awesome if we could get a permalink from a traffic inspector request.

                                      This way, when a client (iOS, webapp etc.) team is working with the proxy API, they could send a permalink of a request containing an error, so that the backend team could quickly see the context (instead of digging into the list of request)

                                      6 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

                                        There is an inspector overhaul scheduled. While I cannot promise any ETA, this is definitely part of it.

                                      • Api management with Postman

                                        It would be very nice to have option to generate Postman collection directly from Apiary.

                                        http://www.getpostman.com/docs/sharing

                                        19 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…)
                                          under review  ·  Lukas LinhartLukas Linhart responded

                                          That’s a great idea, but I cannot give any ETA now. 3rd party library for apiblueprint → postman would definitely be welcome!

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

                                          • Don't see your idea?

                                          General

                                          Feedback and Knowledge Base