Writing resources containing arbitrary data

When you need to write any arbitrary data (e.g. containing multiple-newlines, special formatting or anything "as-is")...

API Blueprint (FORMAT: 1A) syntax

... then use API Blueprint as a classic Markdown document and indent well or use fenced code-blocks around your desired content. There are two short paragraphs in our API Blueprint Tutorial explaining this behavior as a Note on Indentation.

A short example using fenced code blocks:

+ Response 200 (application/hal+json)
    + Headers
        Link: ;rel="self",;rel="gists"
    + Body
          "_links": {
              "self": { "href": "/" },
              "gists": { "href": "/gists?{since}", "templated": true }

Apiary Blueprint (legacy) syntax

...by default Apiary Blueprint uses two newlines (\n\n) as resource separator. Thus, data presented after those will be understood as comments (description) for the next resource or section.

You may choose your own separator usign so-called "heredoc" syntax: start your request/response body with <<<$delimiter string, where $delimiter is not present in your body.

For example, if you wanted to have resource that returns multiple/related data:

GET /multipart-example
< 200 < Content-Type: Multipart/Related; boundary=example-1 <<<EOT --example-1 Content-Type: Application/X-FixedRecord Content-ID: <950120.aaCC@XIson.com> 25 10 34 10 25 21 26 10 --example-1 Content-Type: Application/octet-stream Content-Description: The fixed length records Content-Transfer-Encoding: base64 Content-ID: <950120.aaCB@XIson.com> T2xkIE1hY0RvbmFsZCBoYWQgYSBmYXJtCkUgSS BFIEkgTwpBbmQgb24gaGlzIGZhcm0gaGUgaGFk IHNvbWUgZHVja3MKRSBJIEUgSSBPCldpdGggYS BxdWFjayBxdWFjayBoZXJlLAphIHF1YWNrIHF1 YWNrIHRoZXJlLApldmVyeSB3aGVyZSBhIHF1YW NrIHF1YWNrCkUgSSBFIEkgTwo= --example-1-- EOT

Feedback and Knowledge Base