1

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?

1 Answer 1

2

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.

3
  • 1
    Thanks @Daniel , appreciate the quick response. Looking forward for the fix.
    – GreenDroid
    May 6, 2015 at 21:38
  • Any update on this? Not having this is quite a drawback. Request body properties should be "describeable"since the very first moment.
    – Stefan
    Jul 31, 2015 at 15:52
  • 1
    My bad; it's already there in V.2 - I was stuck on V1.8. Thank you and keep it up.
    – Stefan
    Jul 31, 2015 at 16:36

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.