Rappresentazioni di risorse e strumenti di documentazione dell'API REST

Question

Rappresentazioni di risorse e strumenti di documentazione dell'API REST

#1 da (7 voti)

5

Non mi sento sicuro di cosa significhi esattamente avere rappresentazioni diverse di una risorsa RESTful. L'esempio canonico prevede che un'API fornisca un endpoint, ad esempio /v1/users/:id , e consente al client di selezionare la migliore rappresentazione della risorsa tra JSON , XML , HTML o PDF a seconda dell'intervallo di media valore delle intestazioni ACCEPT .

Avevo l'impressione che questa definizione di rappresentazione potesse essere estesa per comprendere più che semplici tipi di contenuto, ma in realtà schemi di risposta. Supponiamo ad esempio che un cliente desideri informazioni estese sull'utente che potrebbero ottenerlo specificando un'intestazione supportata.

Quindi, ad esempio, la mia applicazione potrebbe fornire diversi schemi per la stessa risorsa, ad esempio

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

Sto capendo correttamente il concetto di rappresentazioni in REST? Oppure il concetto di rappresentazioni delle risorse è applicabile solo ai tipi di contenuto e alla negoziazione del contenuto?

Se sì, come posso documentare le varie rappresentazioni che la mia API può restituire? Non sembra uno dei grandi strumenti di documentazione ( swagger.io o RAML ) supportano la documentazione di più rappresentazioni dello schema di una singola risorsa.

api-design rest documentation-generation

posta Jason 05.01.2016 - 03:00

fonte

1 risposta

Leggi altre domande sui tag api-design rest documentation-generation

È in esecuzione "milli": i marchi sono una buona idea? Come gestire i parametri singolari e plurali per le funzioni

score 7 · Accepted Answer

link

Hai perfettamente ragione nella comprensione delle rappresentazioni, E il modo RESTful per ottenere una rappresentazione diversa di una stessa è tramite la negoziazione del contenuto, utilizzando un tipo di media standardizzato tra il client e il server.

In HTTP, il modo standard per eseguire la negoziazione di rappresentazione / contenuto è utilizzando l'intestazione ACCEPT (RFC 7231 # section-5.3.2), con gli intervalli di supporti standardizzati (RFC 6838 # section-4.2).

Penso a schemi di tipi di media, usando le faccette "." e il suffisso "+" parte dello schema di denominazione del tipo di supporto dovrebbe essere consentito e incoraggiato. Quell'estensione che hai fatto, IMHO è anche il modo giusto e pragmatico per farlo.

RAML supporta rappresentazioni multiple:

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