I suggest you ...

Support multiple content formats

Our API allows switching response and PUT/POST content between JSON and XML, based on Accept headers and/or a query parameter. It's awkward to document both formats. Currently, I am duplicating the docs for every call.

It would be ideal to be able to put both formats in the request/response sample data in the blueprint, maybe based on the Accept or Content-Type header values, and then switch between them, or have a global switch that uses on or the other based on a reader's choice.

See the Shopify API docs for an example (the Format dropdown at upper right):

http://api.shopify.com/index.html

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…)
    Stewart BuskirkStewart Buskirk shared this idea  ·   ·  Admin →
    completed  ·  Jakub KorálJakub Korál responded  · 

    Apiary mock server now supports basic server-side Content Negotiation.

    If your request contains Accept (or Accept-Charset, Accept-Language, Accept-Encoding) header(s), Apiary will count “quality” of each available Response and return the finest one.

    8 comments

    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)
      Submitting...
      • Mohamed MeligyMohamed Meligy commented  · 

        I also want this so much. I need to have an API where an authentication header is passed, based on sample data I return success or suspended status, and by default if the header is not included I return unauthorized.

      • Anonymous commented  · 

        This is also important if you are building API's based on the OData specification. The protocol specifies that the API-user should be able to specify XML or JSON either in the header or using a $format parameter.

        http://www.odata.org/introduction

      • PetrPetr commented  · 

        Thanks Lukas,

        as the original poster mentions, it's not just response formats, but also the POST/PUT payloads / message bodies, that will need to support this. Currently we can only have multiple responses, not multiple request formats.

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hello,

        thanks for the feedback. Please document your APIs with multiple-response format for time being, I am certain we will build this feature on top of that.

        Content negotiation is certainly one of the things we want to support.

        Regards,

        Lukas

      • PetrPetr commented  · 

        This would be very helpful to me as well. I do content negotiation based on the Accept header (or Content-Type for submitting requests) so to describe both, XML and JSON responses would be great.

        Although the documents are the same (structure-wise), my clients who use the JSON version cannot use the mock API, because I can only describe it using one syntax (XML in my case).

      • Stewart BuskirkStewart Buskirk commented  · 

        They are essentially the same. The XML form avoids using attributes, and a JSON array is represented differently than in XML - JSON would have an array called "itemlist", and the XML form would have an element "itemlist" containing a number of "item" elements. That's the only major difference other than value encoding.

        The server builds responses using a single data entity, which is then rendered/serialized as needed into JSON or XML.

      Feedback and Knowledge Base