Representações de recursos e ferramentas de documentação da API REST

5

Eu me vejo inseguro sobre o que exatamente significa ter diferentes representações de um recurso RESTful. O exemplo canônico é que uma API fornece um endpoint - digamos /v1/users/:id - e permite que o cliente selecione a melhor representação do recurso entre JSON , XML , HTML ou PDF dependendo da faixa de mídia valor dos cabeçalhos ACCEPT .

Fiquei com a impressão de que essa definição de representação poderia ser estendida para abranger mais do que apenas tipos de conteúdo, mas, na verdade, esquemas de resposta. Digamos, por exemplo, que um cliente deseje informações estendidas sobre o usuário, especificando um cabeçalho suportado.

Então, por exemplo, meu aplicativo pode fornecer diferentes esquemas para o mesmo recurso, ou seja,

# 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"}

Estou entendendo corretamente o conceito de representações no REST? Ou o conceito de representações de recursos é aplicável apenas a tipos de conteúdo e negociação de conteúdo?

Se sim, como posso documentar as várias representações que minha API pode retornar? Não parece ser uma das grandes ferramentas de documentação ( swagger.io ou RAML ) suportam a documentação de várias representações de esquema de um único recurso.

    
por Jason 05.01.2016 / 03:00
fonte

1 resposta

7

link

Você está exatamente certo em seu entendimento sobre representações, E a maneira RESTful de obter essas diferentes representações de um mesmo é fazendo uma negociação de conteúdo, usando um tipo de mídia padronizado entre o cliente e o servidor.

Em HTTP, a maneira padrão de fazer representação / negociação de conteúdo é usando o cabeçalho ACCEPT (RFC 7231 # seção-5.3.2), com os intervalos de mídia padronizados (RFC 6838 # seção-4.2).

Eu acho que os esquemas de tipos de mídia usam as facetas "." e sufixo "+" parte do esquema de nomenclatura do tipo de mídia deve ser permitido e incentivado. Essa extensão que você fez, IMHO é também a maneira certa e pragmática de fazê-lo.

O RAML suporta várias representações:

#%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"}
    
por 05.01.2016 / 06:36
fonte