È legale per un'API RESTful fornire strutture diverse per una determinata risorsa? Come dovrebbe essere modellato?

Question

È legale per un'API RESTful fornire strutture diverse per una determinata risorsa? Come dovrebbe essere modellato?

#1 da (8 voti)
#2 da (0 voti)

3

Sto usando swagger per prototipare un'API RESTful e sono arrivato a una situazione in cui una proprietà fa parte di una risorsa ma non sempre dovrebbe essere riempita.

Diciamo che la mia risorsa è stores .

Gli endpoint di base sarebbero:

GET: /stores - restituisce un elenco di store

GET: /stores/{storeId} - restituisce un singolo store

Il negozio è definito sulla falsariga di:

Store {
  id: integer,
  name: string,
  pictures: array[]
}

Ma quando si restituisce l'elenco dei negozi, anche restituire l'elenco di immagini di ogni negozio è eccessivo. Le immagini devono essere restituite solo per una singola richiesta di negozio.

Sono confuso su come modellare questa situazione. Su swagger, entrambe le risposte ai metodi sono associate a un oggetto store .

Devo dividere store in due oggetti e definizioni in modo che ogni metodo restituisca un tipo diverso anche se solo una proprietà è diversa?

Devo usare un parametro stringa di query in modo che il consumatore possa scegliere se riempire o meno le immagini? Qualcosa sulla falsariga di:

GET: /stores?fillPictures=false o forse

GET: /stores?detailed=false

Quando si sceglie la seconda opzione, la definizione di un singolo store sarebbe la stessa indipendentemente dall'accesso all'endpoint. Ciò significherebbe che una proprietà vuota sarebbe trasmessa al consumatore per ogni richiesta non dettagliata (con immagini). Dovrebbe essere una preoccupazione?

Qualcuno può far luce su come gestire questo scenario in modo RESTful? Forse conosci qualche API con un'operazione simile?

Grazie in anticipo.

api-design rest swagger

posta Rodrigo Lira 11.01.2017 - 16:47

fonte

2 risposte

0

Se hai una relazione molti / molti (ad esempio un'immagine può andare con negozi multipli) vorrei andare con

Store {
  id: integer,
  name: string,
  pictureIds: array[]
}

e un endpoint separato

POST: /getPictures pictureIds: array[]

Se si tratta di una relazione su un negozio per immagine:

Store {
  id: integer,
  name: string
}

POST : /getPicturesForStores  storeIds : array[]

Entrambi questi metodi ti consentono di ottenere un elenco di negozi e di visualizzare tutte le immagini relative a quell'elenco in due richieste senza duplicare i dati.

Il POST è richiesto per le richieste di stile 'get many' in quanto vi è un limite proibitivo sul numero di caratteri consentiti in una stringa di query url

risposta data 11.01.2017 - 16:53

fonte

Leggi altre domande sui tag api-design rest swagger

file di elaborazione SRP riga per riga si può fare un regex motore di ricerca per il web e se sì, come?

score 8 · Accepted Answer

GET: /stores - returns a list of store

GET: /stores/{storeId} - returns a single store

Queste sono due risorse diverse (un negozio e un elenco di negozi), quindi va bene che abbiano dati diversi.

La risorsa che rappresenta un elenco di negozi può contenere solo informazioni sufficienti per consentire al client di navigare nello store che potrebbe desiderare. Quindi potrebbe essere qualcosa di simile

Request
    GET /stores

Response
  200 - OK

  {
    stores: [
      {id: 34, name: "Walmart", url: "/stores/34"},
      {id: 35, name: "Best Buy", url: "/stores/35"}
    ]
  }

Il cliente può quindi navigare verso il singolo negozio per ottenere ulteriori informazioni di cui ha bisogno su un determinato negozio.