Aglio does not allow parameters in the body to be defined as parameters

Aglio, an API Blueprint renderer, does not allow parameters in the body of a request to be included in the parameters section of the the Endpoint specification. It throws parse warning as follows:

parameter '<some_parameter>' not specified in '<some_description>' its '<some_URI_template>' URI template (warning code 8)

A sample Markdown which would replicate this warning is:

## Journey creation [/v1/journeys/{origin}]

### Create journey [POST]
Create a new journey

+ Parameters
    + origin (required) ... origin location of journey
    + destination (required) ... destination location of journey

+ Request
    + Headers

                Accept: application/json
                Authorization: Basic <BASIC_AUTH_TOKEN>

    + Body

                {
                     "destination" : "some_other_place"
                }


+ Response 200 (application/json)

    + Body

            {
            "origin" : "some_place",
            "destination" : "some_other_place",
            "journey_state" : "Not_Started",
            "timestamp" : "<dateuuid>",
            }

The rendered does not like 'destination' to be a parameter, since it is not in the URI template.

My question is, is this a drawback of the tool, or is it an API Blueprint specificaton? Also, maybe, is this definition of a REST endpoint not per standards?

Answers


The correct way to specify message body attributes is using the new MSON attribute syntax, which is used to render JSON and JSON Schema as of Aglio 2.0.

### Create journey [POST]
Create a new journey

+ Parameters
    + origin (required) - origin location of journey

+ Attributes
    + destination: some_other_place (required) - destination location of journey

+ Request
    + Headers

                Accept: application/json
                Authorization: Basic 

In the near future Aglio will render extra information for the attributes.


Need Your Help

Linq2Sql Testing

c# .net unit-testing linq-to-sql

I have test database and a production database. When developing I of course work against that test database then when deploying I have to semi-manually update the production database (by running a ...