New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Message-body Attributes Description #25

Closed
zdne opened this Issue Sep 23, 2013 · 120 comments

Comments

Projects
None yet
@zdne
Copy link
Contributor

zdne commented Sep 23, 2013

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.

This was referenced Sep 30, 2013

@kadishmal

This comment has been minimized.

Copy link

kadishmal commented Oct 16, 2013

Vote up for this. Quite necessary.

@fguillen

This comment has been minimized.

Copy link

fguillen commented Oct 31, 2013

+1

@xurde

This comment has been minimized.

Copy link

xurde commented Oct 31, 2013

Same do I.

@Almad

This comment has been minimized.

Copy link
Member

Almad commented Nov 13, 2013

👍 as well!

@jrep

This comment has been minimized.

Copy link

jrep commented Nov 14, 2013

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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Nov 14, 2013

@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

This comment has been minimized.

Copy link

fguillen commented Nov 14, 2013

@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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Nov 14, 2013

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

@kuba-kubula

This comment has been minimized.

Copy link
Member

kuba-kubula commented Nov 14, 2013

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

This comment has been minimized.

Copy link

jrep commented Nov 21, 2013

@fguillen Point taken.

@sprohaszka

This comment has been minimized.

Copy link

sprohaszka commented Dec 11, 2013

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

This comment has been minimized.

Copy link

rcrooks commented Dec 11, 2013

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

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Dec 16, 2013

@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 #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

This comment has been minimized.

Copy link

bcls commented Dec 16, 2013

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 notifications@github.com 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 zdne referenced this issue Dec 17, 2013

Closed

Traits #47

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Dec 17, 2013

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

This comment has been minimized.

Copy link

jrep commented Feb 4, 2014

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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Feb 4, 2014

@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

This comment has been minimized.

Copy link

BRMatt commented Feb 4, 2014

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

@jrep

This comment has been minimized.

Copy link

jrep commented Feb 5, 2014

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

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Feb 5, 2014

@BRMatt @jrep

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

@cymen-cengage

This comment has been minimized.

Copy link

cymen-cengage commented Feb 6, 2014

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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Apr 10, 2014

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

This comment has been minimized.

Copy link

davidbarton commented Apr 10, 2014

👍

@mishak87

This comment has been minimized.

Copy link

mishak87 commented Mar 30, 2015

There should have been probably newsletter for this feature 😄.

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Mar 30, 2015

@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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Mar 30, 2015

@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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Mar 30, 2015

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

This comment has been minimized.

Copy link

DataGreed commented Mar 30, 2015

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" notifications@github.com написал:

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

This comment has been minimized.

Copy link

pixelyunicorn commented Mar 31, 2015

Finally! 👍

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Mar 31, 2015

@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

This comment has been minimized.

Copy link

thomask commented Apr 7, 2015

Hi, any updates for Apiary yet? Thanks!

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Apr 7, 2015

@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

This comment has been minimized.

Copy link

thomask commented Apr 8, 2015

No worries of course! Looking forward to the release

@robbinjanssen

This comment has been minimized.

Copy link

robbinjanssen commented Apr 8, 2015

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

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Apr 21, 2015

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

screen shot 2015-04-20 at 5 05 38 pm

You can find some examples to get started here:

Please let us know how you like it!

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

Join the chat at https://gitter.im/apiaryio/api-blueprint

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

This comment has been minimized.

Copy link

jrep commented Apr 21, 2015

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
Jack@netgate.net

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Apr 21, 2015

@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 comment has been minimized.

Copy link
Contributor Author

zdne commented Apr 21, 2015

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

@pzurek

This comment has been minimized.

Copy link

pzurek commented Apr 21, 2015

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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Apr 21, 2015

@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

This comment has been minimized.

Copy link

jrep commented Apr 21, 2015

On Apr 20, 2015, at 8:08 PM, Z notifications@github.com 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
Jack@netgate.net

@pzurek

This comment has been minimized.

Copy link

pzurek commented Apr 21, 2015

@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

This comment has been minimized.

Copy link

grojguy commented Jul 12, 2015

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

This comment has been minimized.

Copy link
Contributor Author

zdne commented Jul 21, 2015

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!

@kpande

This comment has been minimized.

Copy link

kpande commented Jan 30, 2016

Sorry if this is the wrong place for this question, I am trying to model the incoming body of a PUT request to create an account,

### Create account [PUT /users]

+ Request (application/json)

        {
            "role": 9,
            "client": 1,
            "username": "newuser",
            "name": "Real Name",
            "email": "newuser@example.com",
            "timezone": "America/Toronto",
            "locale": "en_CA",
            "active": 1
        }

+ Response 200 (application/json)

    + Attributes (object)
        + Include Success
        + data (User, sample) - Newly inserted record is returned upon success

Instead of having JSON embedded, is there a way to use Attributes so there may be format-agnostic output and other fancy treatment by API Blueprint tooling?

By the way, I really do love this suite. It makes life better. 👍

@pksunkara

This comment has been minimized.

Copy link
Member

pksunkara commented Feb 1, 2016

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

@thomask

This comment has been minimized.

Copy link

thomask commented Mar 31, 2016

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

@zdne

This comment has been minimized.

Copy link
Contributor Author

zdne commented Apr 5, 2016

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

@apiaryio apiaryio locked and limited conversation to collaborators Apr 5, 2016

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.