Use of variables in blueprint with apiary

Question

is possible to define some kind of a constant parameter, that we can reuse in several requests? For example, if I have several endpoints and in all of them I need the same id (a book id for example), is there any chance to define once in the document that id and reference it in the example values needed for the request definitions?

Somekind of:

bookId := `563`
...........

Books [/books/{book_id}]

• Parameters
  • book_id (required, number, {bookId})

Thanks in advance.

Answer 1

It sounds like you want to use MSON. MSON allows you to describe objects (like a book), and use the object in requests/responses. Objects can inherit from each other, and values can be overridden in other objects or directly in request/response Attributes section.

Example:

## Example Object(object) - Comment about Example Object
+ 'someKey': `someValue` (string, required) - Required String value

For an example book:

# Data Structures
## Page (object) - A page in a book
+ `pageNumber` (number, required) - The number of the page

## Book (object) - A book
+ `numPages` (number, required) - The number of pages in the book
+ `title` (string, required) - The title of the book
+ `author` (string, required) - The author of the book
+ `pages` (array[object], required) - The pages in the book

## Book Collection (object) - A collection of books
+ books (array[object]) - The books in the collection

# API calls
## Example call [exaple/endpoint]
## Add new book (POST)
+ Request 200 (application/json; charset=utf-8)
    + Attributes (Book)
+ Response 201 (application/json; charset=utf-8)
    + Attributes (Book)
### Get all books (GET)
+ Request 200 (application/json; charset=utf-8)
+ Response 200 (application/json; charset=utf-8)
    + Attributes (Book Collection)