search

apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.65k stars 2.14k forks source link

Reuse headers and attributes? #259

Closed winniehell closed 8 years ago

winniehell commented 9 years ago

I have a model which defines headers and a model which defines attributes:

## Fast [/fast]

+ Model
    + Headers

            X-Fast-Processing: true

## Things [/things]

+ Attributes (object)
    + name (string)

Now I want to use the headers in GET- and PUT-request and the attributes in GET-response and PUT-request. The following does not work:

### Get Things [GET]

+ Request
    [Fast ][]

+ Response 200 (application/json)
    + Attributes (Things)

### Put Things [PUT]

+ Request (application/json)
    [Fast ][]
    + Attributes (Things)

+ Response 200

            Everything fine.

Is there any way to achieve this?

winniehell commented 9 years ago

Putting the headers from Fast into the Things model does not work because I need to reuse the Fast-headers in other resources, too.

pksunkara commented 9 years ago

@winniehell The Model you are defining is a payload. Request and Response are payloads too. So, you can use the following the syntax to reference the payload

+ Request
    [Fast][]

But you can not combine it with other parts in a payload.

PS: Currently, you cannot reuse headers.

pksunkara commented 9 years ago

This might be a duplicate of #17 but I will leave it to @zdne.

winniehell commented 9 years ago

@pksunkara: yep, looks duplicate to me - I don't know why I didn't find that issue. Thank you for the hint! :+1:

pksunkara commented 9 years ago

I would like to keep this issue open and let @zdne decide since #17 is linked to Traits.

winniehell commented 9 years ago

Sure, I don't mind. :tropical_fish:

My primary intention was to find out how to reuse headers and attributes. That problem seems so be solved by Traits as far as I understand it:

## Fast [/fast]

+ Trait Fast
    + Request Headers

            X-Fast-Processing: true

## Things [/things]

+ Trait Thing
    + Properties
        + name (string)

### Get Things [GET]

+ Request
    + Traits
        + [Fast][]

+ Response 200 (application/json)
    + Traits
        + [Things][]

### Put Things [PUT]

+ Request (application/json)
    + Traits
        + [Fast][]
        + [Things][]

+ Response 200

            Everything fine.

Or do I get something wrong?

pksunkara commented 9 years ago

@winniehell Well, the traits was still in proposal stage and is currently in an uncertain state since we now have MSON. So, please keep a look out on further updates.

zdne commented 9 years ago

@winniehell @pksunkara I plan to update and close the traits issue during the course of the next week. To the original question, reusable headers using MSON syntax are definitely planned.

zdne commented 8 years ago

RFC proposal of syntax addressing this issue: https://github.com/apiaryio/api-blueprint-rfcs/pull/3.

Please track and comment on the RFC.

Thank you!