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. Add possibility to change the theme

    Default theme is nice, but not user-friendly.
    gray-white-gray-white %)

    Grouping and header backgrounds are very strange.

    Best, nZeus

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

      This can be done using our enterprise embedding plan.

      However, we do plan to provide this in cheaper plans that will provide limited customisability, such as background or logo.

      We’ll let you know here once it will be available.

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

      • Scrolling to a line with an error

        If I'm seeing a message like "There is a semantic issue at line 314", it'd be nice to scroll the editor to the line 314 with the error. Otherwise I need to do manually.

        As well cross on the left of message is confusing since I think it hides a message.

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

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

              That is a good point. We do have some plans for github’s organisations as well, so we’ll see how it’s going to play together.

            • Sync Blueprint / Preview scrolls

              When working in Blueprint and preview split screen mode; it'd be cool if i could sync the two scroll bars so I can always see the part of the preview i'm working on in the Blueprint.

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

                Good point! For this, we are waiting for some features in parser though, so I cannot provide any ETA yet.

              • Programmable mock server

                Provide an ability to express non-trivial logic for mock server responses.

                Examples are like "If X in incoming header is greater then Y, return response 2 with value of Z equal to 20".

                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…)
                • generate curl commands from the API blueprint

                  I would like to take API blueprint and export it to curl commands which would contain uri (with some custom prefix), verb, request body, and headers defined.

                  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  ·  1 comment  ·  Admin →
                  • fix text cursor alignment in editor

                    Hi, in Linux in Chromium browser I have problem with text cursor alignment in editor. I mean that the editor consider that the letter width is bigger than of the currently shown font. I attach the screenshot which tells you more: http://postimg.org/image/r9rbmf7cl/ (look at the selected text and the cursor on the line 5). I found this issue only in Chromium browser in Linux, Chrome in Windows works fine. Firefox works fine too.

                    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…)
                    • Update URI-template expansion / matching at server-mock to handle ODATA style APIs

                      In trying to use Apiary.io to document/mock our new ODATA style API, I came into an issue. The mocking service does not handle API's that have the following ODATA style /Resource({id}) instead of /Resource/{id}.

                      Details of the spec can be found at the following http://www.odata.org/docs/ (click on the "Open Data Protocol (OData) Specification" and go to "Appendix A: Sample Entity Data Model and CSDL Document").

                      In talking with Jakub Korál through the help system, he indicated that it was due to "Unfortunately this seems as an unsupported URI-template expansion / matching problem at our server-mock. I am sorry about that…

                      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…)
                      • Bookmarking an API

                        I've just open http://docs.fakturoid.apiary.io/ and wanted to bookmart/favorite it in my account for later use and reference but it is currently not possible at Apiary. Please consider some bookmarking feature. Thanks.

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

                          This (or similar) is certainly on our roadmap as we want to encourage API discovery and collaboration.

                        • Improve navigation in Blueprint view

                          For large APIs with 30+ objects navigation becomes quite difficult in Blueprint view. It would be great if there was some kind of index (as in the Documentation view) that allowed navigation to a particular object quickly.

                          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 →
                          • Allow generate response attribute as random value

                            for example:

                            {"response":OK, "recordid":@random(100000)@}

                            15 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

                              We are investigating such options under an umbrella term of “Programmable mock server”.

                            • 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…)
                              • should introduce multiple sheets / tabs for the same blueprint

                                As your APIs grow, more objects are added the the responses and the size (the height) of the document grows considerably. After a while it gets quite uncomfortable. I suggest to introduce multiple sheets / tabs for the same blueprint to help developers separate their api descriptions by any logic they want.
                                Also gotta mention, that this project is by far the best attempt I've seen lately to improve api design tooling. Keep up the good job guys!

                                24 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 have support for splitting blueprint into multiple files. One of the reasons it’s in alpha is no support for this in editor — so we’ll definitely plan to fix that.

                                • allow create/POST call documentation within the resource

                                  Most create/post calls will call a parent URL to the resources URL itself (i.e. POST /things instead of POST /things/{id}). Currently documenting a POST request within a resource section will generate a POST URL within the documentation that includes the /{id} postfix.

                                  It would be nice to either be allowed to (optionally) supply the proper URL for a POST request or introduce a convention that /{id} postfixes are shaved off of the base resource URL.

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

                                    That is a great point! We’re going to try to come up with proper syntax. Ideas & feedback welcome!

                                  • 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…)
                                      under review  ·  1 comment  ·  Admin →
                                    • Support Tables and/or GitHub-Flavored Markdown

                                      Tables are be very useful for displaying certain types of API information. While tables aren't a "native" feature of Markdown, there are extensions available that provide support.

                                      Even better would be supporting GitHub-Flavored Markdown to provide consistency with how people do things over there already.

                                      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 →
                                        under review  ·  ZZ responded

                                        Currently only some features of GFM are supported (fenced code blocks & new lines).

                                        Support for tables is indeed an interesting feature. It is very likely for a future revision of API Blueprint to support GFM-style tables.

                                      • Support for binary content

                                        Provide a way to return binary content from resource.

                                        29 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…)
                                        • Seperate windows/tabs for editor & preview

                                          It would be very useful to open in seperate windows/tabs editor and preview, e.g. on dual view mode displays what will make it more readable and easy to develop.

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

                                          General

                                          Feedback and Knowledge Base