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. smart resource reference links inside API description

    It would be pretty cool if it were possible to insert a link to a reference anywhere in the blueprint which would load the resource specification in the 'machine'-Part (blue right pane in 'New Document' format) when clicked.

    Especially useful in the introduction part of the API where I usually explain which resources and in which sequence are to be called for accomplishing more complex API usage scenarios.

    Regards,
    Maxim

    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

      If you click on the resource and machine column opens, the URL changes.

      If you access this URL directly, you are going to end up on a page with the machine column open in the proper state.

    • Fix rendering of numbered lists in new apiary blueprint

      In the new apiary blueprint, numbered lists in markdown (for example, 1.) render as bullets. This wasn't a problem in the old blueprint, where they rendered correctly as numbered lists.

      We are working on adding examples and use cases to our API doc so that users can perform complex tasks requiring multiple API calls in sequence. We can don't this without numbered steps. Please fix!

      Otherwise, keep up the good work :)

      0 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 →
      • Revise header handling in Visual Basic code examples generated by Apiary

        Some "restricted" headers cannot be added to WebRequest objects the way generated code examples suggest.

        For instance, if an "Accept" header is included in a blueprint, apiary.io would generated VB code containing:

        <code>
        request.Headers.Add("Accept", "application/json")
        </code>

        which is not correct. "Accept" and some other headers needs to be handled with specific properties, like this

        <code>
        request.accept = "application/json"
        </code>

        I think this entry in stackoverflow explains the issue (and solution) well: "http://stackoverflow.com/questions/239725/cannot-set-some-http-headers-when-using-system-net-webrequest&quot;

        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…)
        • Add the ability to report/track bugs in the support forum, not just feature requests.

          Is there nowhere to report, track, and discuss bugs in Apiary? Should I post each bug as a new idea (e.g. "Please fix ...")?

          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

            Please use either intercom in-application, or e-mail to support@apiary.io.

            We try to fix those quickly, so there should be no need to discuss those. If some are long standing, please create a workaround question on Stack Overflow and we can discuss it there.

          • Allow for URI overrides for resource-oriented APIs

            For resource-oriented declarations, if I put querystring params on resource URI then everything inherits those querystring params. I hate this behavior, so tend to write my docs in a non-resource-oriented way which is less productive and generates less attractive and less readable docs.

            For a concrete example, say I have a users collection with paging:

            ## Users Collection [/users{?page, per_page}]

            and a standard GET method:

            ### Get a collection of users [GET]

            and I add a POST method to the collection to add a user:

            ### Add a user [POST]

            Now the generated documentation creates the "add a user" URI…

            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…)
            • make it easier to find the "invite" button

              since the latest redesign, the invite button is buried under my name. took me a long time to find it. it used to be in the bar across the top and very visible.

              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  ·  1 comment  ·  Admin →
              • Provide the parser for API blueprints for local use

                I prefer to create the markdown for my API using vim locally, rather than through the web interface. The problem is I can't get a live preview. If I had the script and css that turns API blueprint markdown into documentation I see on your site, I could work locally and use LiveReload, then when everything was done I could paste it into the website.

                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 actually done, althrough more improvements are coming.

                  1) You can use “apiary preview” command from our CLI. This does server roundtrip, but gives you full HTML preview.See https://github.com/apiaryio/apiary-client

                  2) You can happily hack around our parsers.

                  Current version is this one: https://github.com/apiaryio/blueprint-parser

                  However, we are going to switch to new format soon. That is OSS to: see https://github.com/apiaryio/snowcrash and follow links to bindings.

                • 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…)
                  • Show schema in documentation

                    I'm looking at the generated documentation, and I can't see a representation of my JSON schema validations anywhere. It would be nice to publish the schema with the API documentation!

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

                      Schema is now shown below the response with “Schema: Response” label.

                    • Add the capability to group api's under an organisation structure

                      Same concept as github organisations but for blueprints.

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

                        Organisations are available. Please write us at support@apiary.io if you want to try them out.

                        They’ll be probably released publicly together with pricing plan.

                      • Support mobile tablet devices

                        While waiting for a flight I tried using the app and the editor didn't work on my iPad.

                        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  ·  Jakub KorálJakub Korál responded

                          Released a touch-only-hack that enables standard Textarea = Which results into enabling code manipulation on touch devices, preferably tablets.

                        • Support HEAD HTTP method

                          Add option to document HEAD method to highlight the fact it's possible to make HEAD requests and show it as an example explicitly.

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

                            Despite Apiay.io mock server automatically supports HEAD method where GET is defined, you can now use explicit HEAD method statement.

                          • to do not commit on each save

                            Our API documentation is linked to our github repository but since we do not master Apiary's syntax, we still use the apiary "blueprint" to edit it, and the "Document" to check the results but this however requires us to save the current doc which in turn requires a commit leaving our repository full of chunked commits and partial changes.

                            It would be great if you add a commit button, or other UI to allow us to commit only when we feel is appropriated.

                            Cheers.

                            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  ·  Jakub KorálJakub Korál responded

                              Just go to the editor on Apiary and click on the blue button Preview – a sandboxed temporary (without Try it, Debugger or Comments) version of documentation appears…

                              It refreshes automagically, after 1 second of last key-press inactivity in the editor.

                            • Provide a way to call PATCH

                              Until Apiary moves to better provider, provide a "standard alternative" (as in google api et al) way to call PATCH method:

                              POST /uri
                              X-HTTP-Method-Override: PATCH

                              would match the blueprint's
                              PATCH /uri

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

                                Patch is now supported on heroku.

                                Support for x-http-method-override in our framework, so incoming soon.

                              • Use json-schema to describe data types

                                The API blueprint description (http://apiary.io/blueprint) mentions the beginnings of using JSON schema to describe the response body.

                                I'd like to +1 that idea, and suggest linking to / embedding http://www.jsonschema.net/

                                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…)
                                • Add HTTPS connection

                                  Currently accessing site with SSL gives certificate warning with heroku.com as the server name. Styles and scripts are broken.

                                  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

                                    4th level domain support is not planned yet. When HTTPS version is not working properly, we have added redirects to HTTP version so one should not encounter broken page.

                                  • Create package for Sublime Text

                                    Create package with syntax highlighting for apiary blueprint format.

                                    21 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

                                      Thanks to Paul Eipper, author of Sublime Apiary Blueprint package, you can now enjoy syntax-aware editing of your API Blueprint in Sublime Text 2.

                                      Available in Sublime Package Control: Install Package > Apiary.io Blueprint.

                                      Thank you Paul.

                                    • Faster Code Syntax Highlighting

                                      I have just noticed that shBrushPython.js, specifically the RegExp for string detection between single quotes (i.e. /'(?!')(?:\.|(\\\')|[^\''\n])*'/gm ) brings my Chrome to a freeze for some good minutes.

                                      Short-term, my humble suggestion is to take some time and do some quick benchmarking with some alternative syntax-highlighters, like
                                      https://github.com/LeaVerou/prism/
                                      or https://github.com/ccampbell/rainbow
                                      Maybe you have already done it, but altogether syntaxHighlighter has some rather costly parsing which makes me skeptical about using it for big projects.

                                      Long-term, maybe you can do the logical thing - move the syntax highlighting to the server, and do it ONCE and ONLY ONCE.
                                      Or maybe I…

                                      0 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…)
                                      • Enable code folding in the Blueprint editor.

                                        Some of my API responses are huge and it's hard to navigate large chunks of nicely formatted JSON.

                                        I'd like to just use my local editor and edit via Git, but I don't feel comfortable giving access to all my private repos.

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

                                          Following our December update of our Blueprint editor, code folding is one of the new and shiny features of the newest stable version of ACE (0.1.0) – the editor we use.

                                          Everyone can now enjoy code folding. Simply use the small arrows at the left side (gutter) next to the line numbers.

                                        • Use tree-diff for JSON

                                          Currently, JSON is diffed against examples on a line-by-line text basis. The better approach would be to parse JSON into tree structures and compare those to the examples.

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

                                          General

                                          Feedback and Knowledge Base