Referenced Payloads

[zdne]

Provide the ability to define arbitrary payloads that can be referenced later (similar to the concept of resource object).

[UnquietCode]

+1 this would be really helpful. Right now I have to retype the request each time.

Any thoughts on allowing a top level # Asset Name section which can be used to define shared assets? Reading the docs I thought it was intended to work this way but I guess not.

[zdne]

This issue should be fully covered on the traits level. No additional support for reusable / shared assets besides #20 External Assets is planned at the moment.

---

To be addressed (and closed) with #47.

[UnquietCode]

Sounds great. Thanks.

[jrep]

I'm a little confused here: The FORMAT:1A spec mentions assets, but doesn't illustrate their use. I have been trying to use named assets as repeated payloads (one of my legacy APIs supports both POST and PUT of identical request body, with identical effect, and with identical response body). I can't make it work, but is that because the 1A spec is so brief I just don't get it? Or is this really not-yet-implemented?

[zdne]

@jrep

An asset is any "data blob" used throughout a blueprint. Opaque to the parser. At this moment its form is only a pre-formatted code block.

The only examples for the time being are the message-body or its schema. At the moment (1A) you can't define such an asset somewhere and reference it later.

As part of traits you should be able to define a trait with an body or schema asset and reference it later.
With #20 you will be able to reference an external asset.

What is probably confusing in the current space is the # Asset Name example which is not supported. I will remove it from the specification.

Please feel free to propose any additional clarifications to the spec if needed.

[jrep]

Given how brief the section describing Assets is (in 1A), and the fact that it's not referenced anywhere else, is there any value even in mentioning it?

[zdne]

This is fair point @jrep. Initially I wanted to elaborate on assets in the specification to put an emphasis on the pre-formatted code blocks and the fact that assets are opaque to the parser. But with the API Blueprint Glossary of Terms it is not needed.

I will remove that entry completely. Anything that simplifies and the specification counts.

[zdne]

@jrep I have just pushed a completely restructured API Blueprint 1A specification (for adding 1B features) – https://github.com/apiaryio/api-blueprint/blob/1B/API%20Blueprint%20Specification.md

Please let me know what do you think, requests for improvements? Best comment directly on the commit 704d622 and or pull request proposed changes.

[vhordejcuk]

Referencing sounds great. In situations where resource model is unapplicable.

[zdne]

As per my comments on #47 this feature is covered partially by the introduction of #25 and it will be covered completely when #286 and #20 is implemented. Closing this issue.