Funzioni personalizzate in un'API REST

Question

Funzioni personalizzate in un'API REST

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

6

Esaminando due delle nostre entità Company e Address . Una società ha un billingAddress e un profileAddress .

Non sono sicuro di come implementare una funzione per impostare l'indirizzo di fatturazione rispetto al profilo. Ecco le opzioni che posso vedere:

Crea un nuovo indirizzo utilizzando POST in /address . Aggiorna l'oggetto azienda su /company con profileAddress = {/* the new id of the address */}
Esegui /company/:id?function=updateBillingAddress&{/* rest of parameters go here */}
Esegui /updateBillingAddress?company={companyId}&{/* rest of parameters go here */}
Esegui /company/:id?billingAddress={ /* address data here */ }

Il primo metodo richiede due chiamate e una maggiore responsabilità da parte dello sviluppatore che si collega all'API. Tuttavia, non sono sicuro che i secondi due metodi siano la struttura appropriata.

L'ultimo sembra che potrebbe essere a posto, offre flessibilità per gli aggiornamenti senza la responsabilità di gestire i puntatori o eseguire due chiamate .. ancora incerto.

Qualcuno ha visto l'uso dei metodi 2 o 3 prima. Va bene usare? Perché perché no? Quale suggeriresti di usare e perché?

api-design api rest

posta Matt 24.04.2013 - 20:45

fonte

2 risposte

Leggi altre domande sui tag api-design api rest

Aggregatore eventi ... non riceve risposta, come determinare il completamento? documentazione del codice dattiloscritto [chiuso]

score 1 · Answer 1

Nella mia mente, hai due diversi modi per gestirlo:

1) Una risorsa per domarli tutti:

Per creare una nuova azienda:

 'POST /company'

L'ente POST ha i dettagli completi dell'azienda, inclusi l'indirizzo del profilo e l'indirizzo di fatturazione. Come notato da v0idnull, il valore di ritorno dovrebbe essere un 201 Created con un'intestazione Location con l'URL della risorsa appena creata.

Per impostare l'indirizzo di fatturazione:

Recupera la rappresentazione attuale della società:

GET /company/123

Aggiorna la rappresentazione con il nuovo indirizzo di fatturazione e fai:

PUT /company/123

Con la nuova rappresentazione completa dell'azienda.

Pro

Riduci il numero di richieste per alcuni flussi di lavoro.
Il caching è "più semplice" in quanto è necessario preoccuparsi solo della memorizzazione nella cache di una risorsa.
Più facile da comprendere per più clienti API.

CONS

Se si hanno frequenti aggiornamenti alla risorsa aziendale per diversi motivi, è possibile riscontrare problemi con aggiornamenti simultanei
Nessuna possibilità di avere il controllo della cache a grana fine per i diversi aspetti dell'azienda.

2) Sotto-risorse separate per indirizzo di fatturazione e indirizzo del profilo

Per creare una nuova azienda:

POST /company

La risposta è simile a:

201 Created
Location: /company/123
Link: </company/123/billing_address>;rel=billing_address
Link: </company/123/profile_address>;rel=profile_address

I clienti possono quindi seguire le relazioni di collegamento billing_address o profile_address per aggiornare rispettivamente tali attributi.

Pro

Consente aggiornamenti a grana fine a diversi aspetti dell'azienda con potenziali errori di aggiornamento potenzialmente meno frequenti.
Memorizzazione nella cache fine di ciascuna risorsa.
Usando i link / ipermedia, puoi ristrutturare URL / applicazione più tardi.

CONS

Richiede più richieste per molti flussi di lavoro (client mobili?)
Più difficile da convincere per alcuni utenti dell'API che non hanno familiarità con le API hypermedia.

score 0 · Answer 2

Dipende ...

Come lo farei io:

PUT /company

I paramter della compagnia sono nel corpo della richiesta in qualsiasi formato desideri supportare. Dovrebbe restituire un 201 creato con l'URL della nuova società nell'intestazione Location.

PUT /address

Come per PUT / azienda. Stessa funzionalità.

L'indirizzo di fatturazione è una risorsa secondaria di / company / [company-id] quindi:

PUT /company/[company-id]/billingAddress

I parametri del nuovo indirizzo di fatturazione potrebbero essere solo l'URL dell'indirizzo creato inizialmente.