Message-body Attributes Description

[zdne]

Documentation of message-body attributes. Similar to URI parameters.

Also if possible it should be clearly differentiated between the URI parameters description and Body Parameters description. Current state with the parameters section of a resource (action) might lead to confusion what parameters are discussed.

[kadishmal]

Vote up for this. Quite necessary.

[fguillen]

+1

[xurde]

Same do I.

[Almad]

👍 as well!

[jrep]

For the "differentiated between the URI parameters description and Body Parameters" part of the task, please be sure to allow an easy way to say "you can provide these parameters either in the body or the URI; same parameters, same meaning." That's how Rails works (I think, actually, it merges the two parameter sets, but anyway the Rails server-side developer can't really tell how the parameter came in).

[zdne]

@jrep

If I understand you right what you are saying is that you basically do not want to differentiate between these two (URI parameters and request body parameters) for requests in certain APIs.

To be frank I am struggling to imagine how to capture this at all. Assuming URI + query parameters are superset to request message-body parameters but yet you do not want to mix these or even send two, possibly disjunctive, sets.

[fguillen]

@jrep

I don't see any point of adding URI params in a POST request and I don't see any way of adding BODY params in a GET request, and since @apiaryio is categorizing the documentation by request method there is not possibility of mixing BODY params with URI params.

So I'm with @zdne and I rather to be specific on describing where my back-layer is expecting to find the params.

[zdne]

Thanks for input. I will post here a syntax proposal within next few days.

[kuba-kubula]

Maybe, I would prefer an option to say "a parameter is a PATH, or QUERY, or BODY, or HEADER, or ... whatever" role or belongsTo ... (needs better naming).
we now use
resource.parameters.id.type, what about resource.parameters.id.role = 'query' ?

[jrep]

@fguillen Point taken.

[sprohaszka]

Message-Body Parameters may be considered as a Model (indeed it is what you did when you POST a resource).
Maybe a solution can be to add to the Model section the same structure as the Parameter section, with type details and requirement.
WDYT ?

[rcrooks]

@zdne Stephane's idea would meet the needs of our developers too if it can be done.

[zdne]

@sprohaszka @rcrooks

Indeed! Something such as

+ Response 200 (application/json)
    + Parameters
        + message (string) ... Message for the world

    + Body

            { "message": "Hello Wordl!" }

Was my initial take on this. However there are following issues to be resolved first:

1. Name of the section (keyword)

   I feel the name "parameters" is quite ambiguous. It might work well in the case of HTTP request message. But probably not so in the case of HTTP response and probably even worse in the case of Model. Other keywords I was thinking include Attribtues, Keys or Properties (which I like the most at the moment).

2. Clarity

   Related to previous point: It must be clear that this section is intended for properties of the model not URI parameters.

3. Nested keys

   It should be possible to discuss nested properties. This would be pretty much solved by Nested Message-body Attributes #28

4. Additional values for URI parameters

   Occasionally it my be useful to specify value of related URI parameter too. E.g.

     # Resource [/resource/{id}]
   
     + Parameters
         + id (number) ... ID of our Resource.
   
     ## Retrieve [GET]
     + Response 200 (application/json)
         + URI Parameters
             + id = 42
   
         + Properties
             + message (string) ... Our message.
   
         + Body
   
                 { 
                     "id": 42,
                     "message": "Hello World"
                 }
   

[bcls]

Properties works for me — and I think that takes care of 2. Agree on 4 that there might be cases where you have both URI parameters and model properties, though I don’t think that is the case for any of our APIs currently.

Robert
Robert Crooks | Director of Learning Services | Brightcove, Inc. || P: 617.245-5090 | M: 617.584.6128 | Twitter: http://twitter.com/BrightcoveLearn/

On Dec 16, 2013, at 6:12 AM, Z [email protected] wrote:

@sprohaszka @rcrooks

Indeed! Something such as

• Response 200 (application/json)

  • Parameters

    • message (string) ... Message for the world

  • Body

    { "message": "Hello Wordl!" }
    

    Was my initial take on this. However there are following issues to be resolved first:

Name of the section (keyword)

I feel the name "parameters" is quite ambiguous. It might work well in the case of HTTP request message. But probably not so in the case of HTTP response and probably even worse in the case of Model. Other keywords I was thinking include Attribtues, Keys or Properties (which I like the most at the moment).

Clarity

Related to previous point: It must be clear that this section is intended for properties of the model not URI parameters.

Nested keys

It should be possible to discuss nested properties. This would be pretty much solved by #28

Additional values for URI parameters

Occasionally it my be useful to specify value of related URI parameter too. E.g.

Resource [/resource/{id}]

• Parameters

  • id (number) ... ID of our Resource.

  Retrieve [GET]

• Response 200 (application/json)

  • URI Parameters

    • id = 42

  • Properties

    • message (string) ... Our message.

  • Body

      { 
          "id": 42,
          "message": "Hello World"
      }
    

    —
    Reply to this email directly or view it on GitHub.

[zdne]

With the relation to #47 this would be the new structure of a payload in 1B:

+ Payload (<media type>)

    [<description>]

    + Traits
        <traits>

    + Parameters
        <uri parameters>

    + Properties
        <entity-body properties>

    + Headers
        <entity-headers>

    + Body
        <entity-body> 

    + Schema
        <entity-schema>

Refer to Use of Parameters & Attributes in API Blueprint and Related Format Changes in 1B.

[jrep]

Is it too late to register reservations about calling this thing "Properties"? I'm in the middle of guiding contributors in converting a couple dozen blueprints from legacy format to FORMAT: 1A. This involves a frequent discussion about how to deal with "the information presently proposed to be called Properties." The word is really abstract; even the developers who have Properties to document are confused and put off by it; everyone's afraid the readers won't have a clue.

In most of the text here, people called these things "body parameters." If that's the natural designation, maybe it should be the formal one. Any chance of an ID phrase ("+ Body Parameters") instead of just a single word ("+ Properties")?

[zdne]

@jrep

Thanks for your input! We have discussed this a lot and here are two main objectives against the word "parameter":

• very likely to be confused with URI parameters and URI query parameters
• in fact it is has the parametric role only in the context of an HTTP request message-body

To build a common ground towards the proposed Resource Blueprint and in the spirit of Attribute-value pairs and I would go with attributes for 1B.

Either as + Body Attributes or just + Attributes. Would this be plausible?

[BRMatt]

I prefer attributes or payload attributes to properties, but just to be devil's advocate what about structure or body structure/payload structure?

[jrep]

I'll settle for any of the "body XXX" or "payload xxx" forms. If we have that, I can be neutral on XXX.

[zdne]

@BRMatt @jrep

If nobody has any objections let's go with Message-body attributes – + Body Attributes.

[cymen-cengage]

What is the current status? Is it possible to test an endpoint that requires application/x-www-form-urlencoded? If so, is there an example of this? By possible, I mean without putting the url-encoded values in as a string.

Update: http://stackoverflow.com/questions/19840554/how-to-format-a-post-request-on-apiary-io

That example does indeed have the values url-encoded but happy I can at least do it that way until 1B is out. This whole discussion made me wonder how to tell what blueprint version dredd supports and it was not clear how to find the answer to that question.

[zdne]

Here is the proposal of Markdown Syntax for discussing body attributes / properties:

MSON: Markdown Syntax for Object Notation

I have made it as a separate repository as I think it is cool and useful enough to live as a stand-alone syntax even tho its initial implementation will be most likely available only as a part of API Blueprint parser.

Note this syntax allows us not only to discuss the attributes of payload / models but to completely avoid writing Body and / or Schema sections while providing the same functionality (no more indented Markdown code blocks, yay!).

In addition it opens the door for embedding (reusing) assets within another assets (item and collection) and much more!

Please let me know what do you think. I would like to start with the implementation within days!

[davidbarton]

👍

[sebastiaanluca]

@zdne Just for info, will it be a matter of hours, days, weeks, … ? As I'm currently writing documentation with attributes and would like to know if I should postpone it to avoid writing the attributes section twice :)

[mishak87]

There should have been probably newsletter for this feature 😄.

[zdne]

@quagh for parser & tools we are looking at hours, for Apiary we are looking at days (=this week), (@Baggz correct me if I am wrong 📦 )

[zdne]

@mishak87 Good point! For now we are definitely going to announce it at https://twitter.com/apiblueprint and here. There will be a blog post at Apiary.io once the it is fully supported – news letter is something we are considering as well.

[zdne]

Note the initial implementation at Apiary.io will render only top-level attributes. By this I mean Apiary.io rendered documentation. The syntax and JSON and JSON Schema generation will work from the start.

[DataGreed]

Will tools like aglio work out of the box or should they be updated to
support this?

sent from a small handheld device with autocorrection
30 марта 2015 г. 19:42 пользователь "Z" [email protected] написал:

Note the initial implementation at Apiary.io will render only top-level
attributes. By this I mean Apiary.io rendered documentation. The syntax and
JSON and JSON Schema generation will work from the start.

—
Reply to this email directly or view it on GitHub
#25 (comment)
.

[pixelyunicorn]

Finally! 👍

[zdne]

@DataGreed

Unfortunately not. Tools like Aglio needs to be updated to render the attributes. Once updated to the latest parser you will be able to use the syntax but you won't see it rendered until the tool is updated.

[thomask]

Hi, any updates for Apiary yet? Thanks!

[zdne]

@thomask We have ran into unexpected issues while deploying on production. We are currently working around the clock to fix these. I will keep this thread updated. Sorry about this.

[thomask]

No worries of course! Looking forward to the release

[robbinjanssen]

Using the latest format for our own documentation and it works great! Thanks!

[zdne]

Update: Apiary now supports rendering of JSON and JSON Schema as well as simplified rendering of attributes:

You can find some examples to get started here:

• https://github.com/apiaryio/api-blueprint/blob/master/examples/08.%20Attributes.md
• https://github.com/apiaryio/api-blueprint/blob/master/examples/09.%20Advanced%20Attributes.md
• https://github.com/apiaryio/api-blueprint/blob/master/examples/10.%20Data%20Structures.md

Please let us know how you like it!

Either on Twitter, here (feel free to open a new issue) or at Gitter.

Thank you all for your patience waiting for this – so much needed – feature!

Support for rendering of every feature (nested objects, additional sample values, data structures & more ...) is in the making.

[jrep]

Doesn't seem to work. Attached apib does not render the Attributes info anywhere.

Am I being too eager about your "now"? Did you really mean "as of the next build" or something?

Jack Repenning
[email protected]

[zdne]

@jrep it should be really now as in right know – I can't see any attachment – can you please paste in in the body of the email or directly into GitHub?

[zdne]

This is just a doodle blueprint but it works – http://docs.attributes2.apiary.io

[pzurek]

So happy to see this done. I was waiting for this to start documenting our new API. Now there is nothing holding me back. Starting first thing tomorrow.

Just a little nitpick. It feels like the required parameter doesn't make much sense on a response.
At the same time, if someone uses the same object for the request and response it would make sense to mark certain attributes as read-only (or response-only) to make clear that they cannot be posted back.

[zdne]

@pzurek thanks for your feedback!

The required parameter is related to a property respectively to the data structure, not necessarily in the context of request / responses.

So if you se a property that is required it should be interpreted as "this property MUST occur in the data structure" be it response or request. In the context of a response this should be interpreted as "this property is always present in the response".

When it comes to read-only – this is why we have introduced fixed (think of it as "const") parameter. A property marked as fixed is essentially immutable and required therefore it should be interpreted as "property that is always present and its value cannot be changed"

Let me know whether this makes sense.

[jrep]

On Apr 20, 2015, at 8:08 PM, Z [email protected] wrote:

This is just a doodle blueprint but it works – http://docs.attributes2.apiary.io http://docs.attributes2.apiary.io/Oh, I see it. I was expecting the attributes table to render in the middle, "human" panel, but I see it now over in the right-hand "machine" panel.

My bad.

Jack Repenning
[email protected]

[pzurek]

@zdne I'm not entirely convinced. I subscribe to the view that there are no "optional" attributes on the object in the response. Something may be null or not but if it's a field on an object it should always be included in the payload. Plus I would like my docs to be as clear as possible at first sight with no additional explanation required. But I think I will simply put read-only annotations in descriptions to get around this.

[grojguy]

I hate to complain because there's some neat stuff here, but I'm super disappointed as it appears the new Attributes do not render in the previous document format? If so, that's a major bummer! Not sure why that would not be implemented. Would it not be pretty much the same tabled way the URI Parameters currently render? Am still stuck manually creating markdown tables for Attributes?

Also it would seem that the URI parameters <description> does not render in either the old or new Apiary document format?? Check it out in the Advanced Attributes example. (<additional description> does render.)

+ <parameter name>: `<example value>` (<type> | enum[<type>], required | optional) - <description>
    <additional description>

Am I the only one bummed by this? Is the previous documentation format being deprecated? The new format is a major departure. There's some nice ideas there, but it's nowhere near concise. For us it's far too 'big' and spread-out, and not screen-space-efficient.

[zdne]

Hey @grojguy, I am sorry that you are disappointed with what we do. Please let me clarify few things. The old rendered documentation is at the end of its life, discontinued and will be completely removed soon. I do not think we will add support for rendering the attributes in it. We would really like to hear any feedback on the new rendered documentation and any reasons why it does not work for you.

As for the new documentation – the MSON rendering is not complete there just yet. Please follow the #191 for updates on this.

Thanks!

[pksunkara]

@kpande Request also allows attributes just as exactly as Response does.

[thomask]

Hi, any updates on the progress for attributes with nested objects? Thanks!

[zdne]

Hey @thomask, you can track the progress of works on Apiary renderer in #191 .