Suggestion: a way to specify headers for all responses of a method

[adam-lynch]

So something like:

#%RAML 1.0 Library

uses:
  errors: errors.raml

traits:
  isRateLimited:
    responses:
      headers:
        X-Rate-Limit-Limit:
          type: number
          description: The rate limit ceiling for this endpoint.
        X-Rate-Limit-Remaining:
          type: number
          description: The number of requests left for the time window.
        X-Rate-Limit-Reset:
          type: number
          description: The remaining window before the rate limit resets, in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time).
      429:
        body:
          application/json:
              errors: errors.BaseError[]

Or:

#%RAML 1.0 Library

uses:
  errors: errors.raml

traits:
  isRateLimited:
    responses:
      429:
        body:
          application/json:
              errors: errors.BaseError[]
      //:
        headers:
          X-Rate-Limit-Limit:
            type: number
            description: The rate limit ceiling for this endpoint.
          X-Rate-Limit-Remaining:
            type: number
            description: The number of requests left for the time window.
          X-Rate-Limit-Reset:
            type: number
            description: The remaining window before the rate limit resets, in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time).

[adam-lynch]

My best workaround so far is applying the isRateLimited trait in this library to every method:

#%RAML 1.0 Library

uses:
  errors: errors.raml

traits:
  isRateLimited:
    responses:
      << successResponseCode >>:
        headers:
          X-Rate-Limit-Limit: X-Rate-Limit-Limit
          X-Rate-Limit-Remaining: X-Rate-Limit-Remaining
          X-Rate-Limit-Reset: X-Rate-Limit-Reset
      400?:
        headers:
          X-Rate-Limit-Limit: X-Rate-Limit-Limit
          X-Rate-Limit-Remaining: X-Rate-Limit-Remaining
          X-Rate-Limit-Reset: X-Rate-Limit-Reset
      401?:
        # TODO: maybe rate limiting is different for unauthorized users?
        headers:
          X-Rate-Limit-Limit: X-Rate-Limit-Limit
          X-Rate-Limit-Remaining: X-Rate-Limit-Remaining
          X-Rate-Limit-Reset: X-Rate-Limit-Reset
      402?:
        headers:
          X-Rate-Limit-Limit: X-Rate-Limit-Limit
          X-Rate-Limit-Remaining: X-Rate-Limit-Remaining
          X-Rate-Limit-Reset: X-Rate-Limit-Reset
      403?:
        headers:
          X-Rate-Limit-Limit: X-Rate-Limit-Limit
          X-Rate-Limit-Remaining: X-Rate-Limit-Remaining
          X-Rate-Limit-Reset: X-Rate-Limit-Reset
      429:
        headers:
          X-Rate-Limit-Limit: X-Rate-Limit-Limit
          X-Rate-Limit-Remaining: X-Rate-Limit-Remaining
          X-Rate-Limit-Reset: X-Rate-Limit-Reset
        body:
          application/json:
            errors: errors.BaseError[]
      500?:
        headers:
          X-Rate-Limit-Limit: X-Rate-Limit-Limit
          X-Rate-Limit-Remaining: X-Rate-Limit-Remaining
          X-Rate-Limit-Reset: X-Rate-Limit-Reset

types:
  X-Rate-Limit-Limit:
    type: number
    description: The rate limit ceiling for this endpoint.
  X-Rate-Limit-Remaining:
    type: number
    description: The number of requests left for the time window.
  X-Rate-Limit-Reset:
    type: number
    description: The remaining window before the rate limit resets, in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time).
  # TODO: is a X-Rate-Limit-Window needed?

[kevinduffey]

Curious if you ever finalized this. It would be nice to see a set of commonly used traits that could help others reduce RAML 1.0 documents by reusing traits, resource types, etc.

[jsamr]

@kevinduffey @adam-lynch Would love this feature.

I suggest a way to select responses status in a very flexible manner, i.e.

  //:       # Select optionally all status
  200,304:  # Select 200 and 304 status
  200,304?: # Select 200 and, optionally, 304 status
  2xx:      # Select any successful status optionally
  2xx,3xx:  # Select any status starting with a 2 or a 3 optionally

[kevinduffey]

I think the problem with that is it would be invalid yaml? I think you would have to put the list of codes in quotes and then the RAML parser would need to know if it finds a string, to look for commas, then split it and treat them as individual keys. I do like the way that looks though.