I find myself unsure about what exactly it means to have different representations of a RESTful resource. The canonical example is for an API to provide an endpoint - say /v1/users/:id - and allow the client to select the best representation of the resource between JSON, XML, HTML or PDF depending on the media range value of the ACCEPT headers.

I was under the impression that this definition of representation could be extended to encompass more than just content-types, but actually response schemas. Say for example a client wants extended information about the user they could get it by specifying a supported header.

So for instance, my application could supply different schemas for the same resource i.e.

# get the default user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1+json
 
# server responds with
{"id": 1234, "name": "Jeffery Lebowski"}

# get the extended user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1.extended+json

# server responds with
{"id": 1234, "name": "Jeffery Lebowski", "sport": "Bowling"}

Am I correctly understanding the concept of representations in REST? Or is the concept of resource representations only applicable to content types and content negotiation?

If so, is there anyway to model these different types resource representations using the various API documentation tools? My follow up, are there any API documentation tools that support this type of scheme - where a single end-point can return multiple schema representations of the same resource. It doesn't seem like either of the biggies - swagger.io or RAML handle this at all.

I find myself unsure about what exactly it means to have different representations of a RESTful resource. The canonical example is for an API to provide an endpoint - say /v1/users/:id - and allow the client to select the best representation of the resource between JSON, XML, HTML or PDF depending on the media range value of the ACCEPT headers.

I was under the impression that this definition of representation could be extended to encompass more than just content-types, but actually response schemas. Say for example a client wants extended information about the user they could get it by specifying a supported header.

So for instance, my application could supply different schemas for the same resource i.e.

# get the default user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1+json
 
# server responds with
{"id": 1234, "name": "Jeffery Lebowski"}

# get the extended user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1.extended+json

# server responds with
{"id": 1234, "name": "Jeffery Lebowski", "sport": "Bowling"}

Am I correctly understanding the concept of representations in REST? Or is the concept of resource representations only applicable to content types and content negotiation?

If so, how can I document the various representations that my API can return? It doesn't seem like either of the big documentation tools (swagger.io or RAML) support documenting multiple schema representations of a single resource.