Supporting multiple explicit response bodies for the same http status code


#1

Hi There!

We are currently trying to represent our API spec using RAML and we have the following use case which i cant seem to represent.

Consider the following business function: doSomething(param1, param2, param3).

In our API stack, an HTTP 400 response would be given if validation on the parameters fails. To make it more verbose we supply the failing validations inside the response body for 400. Something like { “PARAM1” : “NULL_OR_EMPTY”, “PARAM2” : “INVALID_CHARS” … }

In this case we could potentially represent this response body as the cross product of all parameters in the method together with the enumeration of possible validation errors (which would be close to the truth) however it is the case that not all parameters can throw all validation errors and we also have the requirement that we need to explicitly list the possible validation errors the API can return.

Am i missing something here? or is this not possible with RAML? It would be great if we could list explicitly "this call could provide X, Y , Z.

Thanks

Kurt


#2

Hi Kurt,

Thanks for the feedback, and for raising this here!

We’ve come across this use-case a few times now, and I believe we should/are trying to address it in RAML 0.9 or 1.0. I’ll point the primary spec authors at this, and hopefully we can get a discussion going around it.

If you’ve got suggestions on a good way to handle it, we’re all ears :-).

//Dillon


#3

i can see two ‘ergonomic’ ways of doing this - either by allowing explicit response bodies (grouped by http status code?) for each method.

Another way which is a bit more specific to my example would be to allow definition of response fragments to validation or other semantic constraints. These would then be group together by the ui generator (and possibly by the code generator as hooks which are then called by the API logic)


#4

I am far from being a RAML guru (and especially not HAML), but the dash-space prefix ("- ") seems to indicate that something is part of a collection/list/array. If that is accurate, wouldn’t it follow that the evolution from a single example to multiple examples would be as follows:

Singular
URI: /some/endpoint/
HAML Path: /verb/responses/500/body/application/json

example: |
{
“error”: “There is only one possible error.”
}

Plural
URI: /some/endpoint/
HAML Path: /verb/responses/409/body/application/json

- example: |
{
“error”: “There ‘username’ parameter is required.”
}
- example: |
{
“error”: “There ‘password’ parameter is required.”
}


#5

I tried, but this doesn’t work.

post:
description: Create a new test in a specific queue.
body:
application/json:
- example: !include …/schema/queue_test/create.json
- example: !include …/schema/queue_test/create.json


#6

Hi,

not sure if that is still needed, but RAML 1.0 now supports the definition of multiple examples. An example:

examples:
  song1:
    description: Example for a song without description and the artist is not a band.
    content:
       title: Yesterday
       artist:
         name: The Beatles
         is_band: true
  song2:
    description: Example for a song with description and the artist is a band.
    content:
      title: How deep is your love
      description: That could be a description for the song.
      artist:
        name: Calvin Harris
        is_band: false

the examples are defined in the new YAML syntax btw.


#7

Hello Christian,

Now that you have song1 and song2 examples, is there a way to select one of them when the request matches some criteria?
If thats possible, can you please point me to the doc page explaining the rules for matching examples.

Thanks
Omar…


#8

That is something which RAML does not have OOTB and needs a bit of annotation magic :wink: You can define an annotation that basically defines that rule, for example, when there is a specific query parameter return this example.