API interna: alcuni metodi generici più grandi o molti metodi molto specifici

1

Sto costruendo una web API che verrà consumata da diversi sistemi interni. Naturalmente i diversi sistemi hanno requisiti diversi. I consumatori possono creare richieste di modifica all'API, quando hanno bisogno di nuove funzionalità. Tutto è nella mia organizzazione. Come faccio a sapere quando una richiesta di modifica è troppo specifica e quando deve essere implementata?

L'API dovrebbe essere una API comune e non specifica per il consumatore , ma verrà utilizzata da diversi sistemi. Quindi diciamo che ho il seguente modello semplice (non posso condividere il mio modello attuale):

public class Customer
{
    public int Id;
    public Order[] Orders;
}

public class Order
{
    public int Id;
    public DateTime Date;
    public Product[] Products;
}

public class Product
{
    public int Id;
    public ProductType ProductType;
}

public enum ProductType
{
    DVD,
    Book,
    CD
}

Un consumatore vorrà recuperare tutti gli ordini per un cliente specifico. Quindi scriverò un metodo specifico per questo:

www.myapi/orders/getByCustomer/1

Questa è una cosa abbastanza comune da fare. Il prossimo consumatore desidera recuperare tutti gli ordini per un cliente specifico, ma solo dove ProductType è DVD . Sarebbe simile a questo:

www.myapi/orders/getByCustomerAndProductType/1/DVD

Ma aspetta , questo può essere ottenuto usando prima getByCustomer , e poi lascia filtrare manualmente il consumatore su ProductType alla fine. Quindi la funzione è già disponibile, ma il consumatore otterrà più dati di quelli effettivamente necessari. Devo accettare la nuova funzione o dovrei chiedere al consumatore di utilizzare il metodo getByCustomer e filtrare i dati alla fine. Come posso decidere quali responsabilità deve avere il cliente e quando la logica deve essere implementata nell'API? Esistono linee guida generali?

Sto pensando di fornire l'API anche come OData, ma poi il cliente sarà responsabile per le query che non gradiscono.

    
posta smoksnes 29.09.2016 - 11:08
fonte

2 risposte

5

Potrebbe essere o non essere "abbastanza comune", ma ci sono soluzioni migliori al problema. Al posto dei parametri di query .

GET /www.myapi/orders?customerId=1
GET /www.myapi/orders?customerId=1&productType=DVD

Un endpoint flessibile ti consente di adattare il tuo contenuto di risposta alle esigenze di diversi clienti.

In generale, è necessario riflettere se i bisogni dei client siano abbastanza diversi da fornire completamente API diverse o se le esigenze di tutti i client possano essere soddisfatte con una singola API.

    
risposta data 29.09.2016 - 17:39
fonte
1

Bene, poiché si tratta di un'API interna, l'azienda ha effettivamente il controllo su tutti i parametri e i vincoli. I team coinvolti e i loro manager possono ora decidere, tenendo conto:

  • La larghezza di banda è importante? Se sì, fai in modo che il produttore attui più filtri, cioè implementa la modifica richiesta.
  • La latenza è importante e la larghezza di banda non è molto limitante? Quindi puoi permetterti di inviare più dati e i clienti hanno una maggiore flessibilità per filtrare i dati desiderati (il che potrebbe cambiare più frequentemente di quanto vorresti cambiare il tuo servizio).
  • Quale squadra ha più risorse al momento? Lascia che facciano il lavoro dalla loro parte.
  • Come principio generale, cerca di offrire servizi basati sulle capacità aziendali. Perché i clienti hanno bisogno di quei dati? Se vogliono solo mostrarlo da qualche parte, ok. Ma forse potrebbe essere più sensato offrire la capacità di business come API di servizio e non i dati che la supportano (vedi questo articolo che parla di SOA ma ha una rilevanza più ampia per qualsiasi tipo di servizio)
risposta data 29.09.2016 - 19:17
fonte

Leggi altre domande sui tag