Traits that respond with the same response code

[chrisspiegl]

It would be great if it would be possible to use two traits for one api end point. And to show that the end point can answer with either one of the two ways.

traits:
  - secured_key:
      responses:
        401:
          body:
  - secured_token:
      responses:
        401:
          body:
/keys:
  is: [ secured_key, secured_token ]

[usarid]

Right now, the last one wins here: but for your example, it wouldn't matter, right? If e.g. the body specifications were different, say two different schemas, then what you're saying is: it'll either obey this schema or that schema. But that's equivalent to saying it'll adhere to a single schema that offers options.

I'm not at all saying your suggestion is invalid: it may be easier to specify multiple responses for a single status code rather than trying to fold all the variability into a single property value. I'd just like to continue digging deeper into specific use cases.

[chrisspiegl]

For me the specific use case would be that the body schema would be the same but the answer for those special traits is defined:

secured_key

example: |
  {
    msg: 'access_denied_key'
  }

secured_token

example: |
  {
    msg: 'access_denied_token'
  }

[usarid]

You could have a schema for errors, something like:

{ 
    "$schema": "http://json-schema.org/draft-03/schema",
    "type": "object",
    "properties": {
        "msg": {
            "type": "string",
            "enum": [
                "access_denied_key",
                "access_denied_token"
            ]
        }
    }
}

which could cleanly enumerate all reasons for a 401.

But regardless, we're definitely considering expanding the spec to allow multiple examples, maybe under an examples property that's a peer of the example property. We're also contemplating a bodies root-level property, a peer of traits, that defines body patterns, each of which has a schema, example, and examples properties (all optional).

[t1]

Using a plain 400 may make the point more evident. Often there are several reasons for a request to be bad; numerous validations can fail. I may want to document them, but even if they use the same status code, they may be completely unrelated and even come from different, e.g., validation libraries. So returning one object schema with an enumeration for the valid types would not be an option.

[CoderSpinoza]

Also encountered into a similar problem.

traits:
  postApi:
    responses:
      400:
        body:
          application/json:
            properties:
              code:
                type: integer
                enum: [-601]
                description: Not using this service
  uploadApi:
    responses:
      400:
        body:
          application/json:
            properties:
              code:
                type: integer
                enum: [-602]
                description: Too large image
/api:
  /post:
    is: [postApi]
  /upload:
    is: [postApi, uploadApi]

This results in restriction conflicts of enum between -601 and -602 with raml js parser, though what I tried to describe is two valid possible error codes -601, -602. What would be the best way to describe these two kinds of error responses?

[jstoiko]

Have you thought of using Resource Type and Trait Parameters to dynamically pass a value to the trait-response-code's enum?

[t1]

@jstoiko : Can you give us an example of how resource types and trait parameters can help with multiple responses using the same code?

[AjainK]

@t1: Im stuggling with the above scenario where multiple responses are possible for the same status code. I went through the RAML documents and still was unable to find a valid solution for the mentioned scenario. I can see the comment is 2 years old , do you have any solution now for the same?.

[t1]

@jstoiko: No, I gave up. And OpenAPI isn't any better.