Adding comprehensive response headers to resourceType


#1

I’m declaring an API and the resourceType looks like this:

resourceTypes:
	- base:
		get?: &common
			responses:
				200:
					headers:
						x-ratelimit-limit:
							type: integer
						x-ratelimit-remaining:
							type: integer
						x-ratelimit-reset:
							type: integer
				400:
					headers:
						x-ratelimit-limit:
							type: integer
						x-ratelimit-remaining:
							type: integer
						x-ratelimit-reset:
							type: integer
				404:
					headers:
						x-ratelimit-limit:
							type: integer
						x-ratelimit-remaining:
							type: integer
						x-ratelimit-reset:
							type: integer
				429:
					description: |
						API rate limit exceeded. See http://developer.fisioplex.com/rate-limiting
						for details.
					headers:
						x-ratelimit-limit:
							type: integer
						x-ratelimit-remaining:
							type: integer
						x-ratelimit-reset:
							type: integer
		post?: *common
		patch?: *common
		put?: *common
		delete?: *common

As you can see, I’m repeating the response headers for every single status code. The problem is that I expect some headers to be present in responses for other status codes that today I don’t know will be used. When a specific resource declares a new status code, I want those headers there also.

Includes would make my API definition more concise, but I don’t believe they would solve this specific problem.

Is there any solution I’m not seeing for this issue?

Pax!
Andre Uchoa


#2

Hi Andre,

In the use-case you are envisioning, do you expect the headers to be the same set as are provided in the above resourceType, or the set that are provided above + headers specific to that status code? I have a few ideas on ways to accomplish this, and will ask around w/other RAML experts depending on your clarifications here.

Thanks!

//Dillon


#3

FWIW you can also shorten up the above by doing the following:

resourceTypes:  
    - base:
        get?: &common
            responses:
                200:
                    headers: &commonHeaders
                        x-ratelimit-limit:
                            type: integer
                        x-ratelimit-remaining:
                            type: integer
                        x-ratelimit-reset:
                            type: integer
                400:
                    headers: *commonHeaders
                404:
                    headers: *commonHeaders
                429:
                    description: |
                        API rate limit exceeded. See http://developer.fisioplex.com/rate-limiting
                        for details.
                    headers: *commonHeaders
        post?: *common
        patch?: *common
        put?: *common
        delete?: *common

#4

I don’t know if this is valid syntax. Probably not. But I believe it will clarify what I’m looking for.

resourceTypes:  
    - base:
        get?: &common
            responses:
                2**?:
                    headers: &commonHeaders
                        x-ratelimit-limit:
                            type: integer
                        x-ratelimit-remaining:
                            type: integer
                        x-ratelimit-reset:
                            type: integer
                4**?:
                    headers: *commonHeaders
                429:
                    description: |
                        API rate limit exceeded. See http://developer.fisioplex.com/rate-limiting
                        for details.
                    headers: *commonHeaders
        post?: *common
        patch?: *common
        put?: *common
        delete?: *common

#5

Or even:

resourceTypes:    
    - base:
        get?: &common
            responses:
                *:
                    headers: &commonHeaders
                        x-ratelimit-limit:
                            type: integer
                        x-ratelimit-remaining:
                            type: integer
                        x-ratelimit-reset:
                            type: integer
                429:
                    description: |
                        API rate limit exceeded. See http://developer.fisioplex.com/rate-limiting
                        for details.
                    headers: *commonHeaders
        post?: *common
        patch?: *common
        put?: *common
        delete?: *common

#6

And, when specifying a resource response for some status code, I should be able to add others to those declared in the base resource type.


#7

Hi, Dillon!

Do you believe the ideas you said you had apply to the use case I presented?