Cannot use Traits to define response headers for multiple http response statuses


#1

It appears you cannot use Traits to define response headers for multiple http response statuses. Instead you have to repeat each set of headers for each status code. Please let me know if I’ve missed a trick!

I am using RAML 0.8, but I can’t see that v1.0 is different for traits.

Details

I am happy that I can define a trait for common request headers once for the request - there is only one. What I’d like to do is use that trait for each response too (of which there can be many).

I thought I’d be able to do this:

#%RAML 0.8

...

traits:
 - usingTransactionHeaders:
     headers: 
       X-Client-Transaction-Id:
         description: Unique client reference id that can be traced through our systems
         required: 
           true
       X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
         required:
           true
...

/subpolicies:
  /{subpolicyid}:
    uriParameters: 
      subpolicyid: 
        description: "Used to filter the subpolicies"
    /customerid:
     /{customerid}:
       uriParameters:
         customerid:
           description: "Used to indicate the customer account that requires a transaction context."
       patch:
         description: "Service for updating items in the subpolicy"
         is: [ usingTransactionHeaders ]
         body: 
           application/json:
             schema: UpdateMileageSchema
             example: !include examples/process_policies_v1_update_mileage.json
         responses:
           204:
             description: OK, but no content returned
             is: [ usingTransactionHeaders ]
           230:
             description: OK, see X-Messages header for informational messages
             is: [ usingTransactionHeaders ]
           400:
             description: An error occurred, see X-Messages header for more information
             is: [ usingTransactionHeaders ]
           412:
             description: Validation failed, see X-Messages header for more information
             is: [ usingTransactionHeaders ]
           500:
             description: An unexpected error occurred
             is: [ usingTransactionHeaders ]

But the last 5 is: [] statements are not valid. The trait needs to be applied to a type or a method not a response.

So instead, I need to define the trait as follows:

usingTransactionHeaders:
  headers: 
    X-Client-Transaction-Id:
      description: Unique client reference id that can be traced through our systems
      required: 
        true
    X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
      required: 
        true
  responses:
    200?:
      headers: 
        X-Client-Transaction-Id:
          description: Unique client reference id that can be traced through our systems
          required: 
            true
        X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
          required: 
            true
    204?:
      headers: 
        X-Client-Transaction-Id:
          description: Unique client reference id that can be traced through our systems
          required: 
            true
        X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
          required: 
            true
    230?:
      headers: 
        X-Client-Transaction-Id:
          description: Unique client reference id that can be traced through our systems
          required: 
            true
        X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
          required: 
            true
    400?:
      headers: 
        X-Client-Transaction-Id:
          description: Unique client reference id that can be traced through our systems
          required: 
            true
        X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
          required: 
            true
    412?:
      headers: 
        X-Client-Transaction-Id:
          description: Unique client reference id that can be traced through our systems
          required: 
            true
        X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
          required: 
            true
    500?:
      headers: 
        X-Client-Transaction-Id:
          description: Unique client reference id that can be traced through our systems
          required: 
            true
        X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
          required: 
            true

The above does allow you to provide different descriptions etc for each http response status code, but what if they are all the same? It’s incredibly inefficient, repetitive and inelegant eh? Wouldn’t it be good if you could apply a trait at response level (my first attempt) or use status code ranges (or perhaps wild-cards) e.g.

usingTransactionHeaders:
  headers: 
    X-Client-Transaction-Id:
      description: Unique client reference id that can be traced through our systems
      required: 
        true
    X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
      required: 
        true
  responses:
    200..499?:
      headers: 
        X-Client-Transaction-Id:
          description: Unique client reference id that can be traced through our systems
          required: 
            true
        X-Server-Transaction-Id:
         description: | 
            Unique request reference id that can be traced through our systems - this 
            is guaranteed (bearing in mind the statistical probability of generating 
            a matching UUID...) to be unique per request
          required: 
            true

Wouldn’t that be much more elegant? :confused:

For the time being I am defining my traits in an external file, but I’d be interested to know if there is

  1. a work-around and
  2. any appetite for adding this as a request for the next version of the spec?

Cheers
Jim