Qual è la migliore pratica per gli endpoint API per un'entità?

0

Non so se il titolo rifletta correttamente la domanda, ma posso spiegare di più che scrivere un buon titolo.

Se ho un database che ha ( employees , departments , orders , ecc ...), e ha molti modi per chiamare gli endpoint di questo sistema, e ogni modo richiede ai dati un numero maggiore o minore di la stessa entità (ad es. entità dipendente), supponiamo che sto costruendo gli endpoint employees :

  • Un endpoint per mostrare ai dipendenti tutti a fini di gestione.
  • Uno da utilizzare nei menu a discesa sull'interfaccia utente per scegliere un dipendente (per qualche motivo) e mostrare solo% dipendenti di% di dipendenti.
  • Ne hai bisogno perché in una pagina per un ruolo specifico dovrebbe essere in grado di vedere solo i suoi dipendenti non tutti (e d'altra parte un altro ruolo ha permesso di vedere tutti i dipendenti).

Questo tipo di requisiti è normale e ripetuto in molti sistemi, ma sono perso e ho bisogno di sapere quando mettere i filtri ed è giusto usare un endpoint e fornire molti filtri per questo (come quello per ottenere solo {id, name} ma con filtro per essere in grado di ottenere solo IsActive = true o tutti i dipendenti) o dovrei separare gli endpoint? e a seconda di cosa esattamente?

So che posso usare IsActive = true o GraphQL e faciliterò le cose per me e per i consumatori della mia API, è l'unica soluzione?

    
posta Dabbas 13.02.2018 - 14:16
fonte

1 risposta

2

Non penso che ci sia un accordo universale su questo, ma io uso le seguenti regole pratiche:

  • Se ha senso richiedere l'elenco completo di una particolare risorsa ( tutti dipendenti), allora ci dovrebbe essere un endpoint di primo livello per questo.
  • Se è necessario filtrare su un attributo di una risorsa, quindi utilizzare un parametro di query per quello o creare un endpoint separato. La scelta dipende in gran parte da quanto è necessario il filtro e se esiste un nome ovvio per l'endpoint.
  • Se è necessario filtrare una relazione tra due risorse, utilizzare un nuovo endpoint sotto la risorsa su cui si effettua il filtro. Ad esempio, l'endpoint per i dipendenti che tutti segnalano a un determinato gestore potrebbe essere /managers/<id>/employees/ )
  • Per specificare che vuoi solo un sottoinsieme degli attributi nella rappresentazione della risorsa, usa la stringa di query.

Questo, ad esempio, darebbe le query

GET /employees
GET /employees?active=true
GET /role/<id>/employees?fields=id,name

A volte, potrebbe anche essere opportuno invertire la logica di filtraggio, in modo che GET /employees restituisca solo i dipendenti attivi e GET /employees?include_inactive fornisce l'elenco di dipendenti attivi e inattivi.

Alla fine, prova a progettare la tua interfaccia in modo che il caso comune sia più facile da ottenere per i client.

    
risposta data 13.02.2018 - 15:38
fonte

Leggi altre domande sui tag