Handling multiple extensions for an endpoint


I am trying to set up our API description and we have something where you can call the same endpoint with different extensions to get different items in return. I am wondering how to describe this using RAML 1.0. For example

GET /api/thing/someID.json

WIll return a json represenation of this thing.

GET /api/thing/someID.png

Will return a png image of this thing.

Is there a simple concise way to represent this, or do I have to make different endpoints for each file extension since they return different file types?


I’d do it this way.

GET /api/thing/somejsons/{id}
GET /api/thing/somepngs/{id}


What about using uriParameters? You can express uri as


and specify ext parameter under uriParameters section. Refer to https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#template-uri.