Resource representations and REST API documentation tools

Question

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.

Answer 1

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_2

You are exactly right in your understanding about representations, AND the RESTful way for you to get those different representation of one same is by doing content negotiation, using a standardised media type between the client and the server.

In HTTP, the standard way to do representation/content negotiation is by using the ACCEPT header (RFC 7231#section-5.3.2), with the standardised media ranges (RFC 6838#section-4.2).

I do think media type schemas, using the facets "." and suffix "+" part of the media type naming scheme should allowed and encouraged. That extension you did, IMHO it's also the right and pragmatic way to do it.

RAML does support multiple representations:

#%RAML 0.8
title: REST Content Negotiation Example
version: 0.1
baseUri: http://example.com

/v1/users/:
  displayName: users
  /{id}:
    displayName: id
    uriParameters:
      id:
        type: integer
    get:
      responses:
        200:
          body:
            application/vnd.myapp.v1+json:
              example: |
                {"id": 1234, "name": "Jeffery Lebowski"}

            application/vnd.myapp.v1.extended+json:
              example: |
                {"id": 1234, "name": "Jeffery Lebowski", "sport": "Bowling"}