API REST paging tramite intestazioni

Ci sono diversi negativi possibili quando si prendono in considerazione campi di intestazione personalizzati.

1. I test basati sul browser saranno difficili
2. I proxy a volte rimuovono / distruggono i campi delle intestazioni
3. Interrompe il caricamento in cache HTTP
4. Gli altri sviluppatori non se lo aspettano

Quando si restituisce un elenco dinamico, si desidera disabilitare la memorizzazione nella cache, quindi non dovrebbe essere un problema.

Se non ti aspetti di utilizzare un browser per testare i tuoi endpoint, conosci tutti i proxy che verranno utilizzati e senti di poter documentare il comportamento in modo che gli sviluppatori futuri non saranno sorpresi da questo nuovo comportamento, quindi provalo fuori.

Ho avuto idee simili prima per i campi di intestazione HTTP, ma non hanno mai funzionato. Potresti avere più fortuna.

Per l'impaginazione, dovresti considerare le tecniche descritte in RFC 5005 . Approssimativamente, ogni pagina di risultati è una risorsa separata, che a sua volta contiene collegamenti ipertestuali alla pagina precedente / successiva dei risultati. Quindi, come al solito, l'applicazione può semplicemente seguire i link per navigare da uno stato di applicazione a quello successivo.

L'ortografia attuale dell'uri non ha importanza. È possibile trattare gli intervalli come parte dei parametri di query o come risorse separate in una raccolta di pagine o ...

/some-list?page=3
/some-list/3
/some-list/pages/3
/some-list/records/20?order=ascending&limit=10

Dovrai riflettere se la pagina 3 "adesso" abbia la stessa rappresentazione della pagina 3 in un altro momento. In caso contrario, potresti voler reindirizzare queste risorse a un altro identificatore con una durata di memorizzazione nella cache migliore.

Alcune API identificheranno le risorse di paging inserendo i dati di impaginazione nel percorso; che non è particolarmente adatto se si ritiene che il percorso debba rappresentare la posizione di una risorsa in una gerarchia. I parametri di query sono molto più adatti.

Poiché ciò che stai facendo è una query sicura (nessuna modifica allo stato del server), GET, piuttosto che POST, è sicuramente il metodo corretto da considerare.

Anche se è necessario consentire al client di specificare i parametri di query (al contrario di definire i collegamenti di paginazione all'interno dell'ipermedia), si dovrebbe comunque trattarlo come un semplice GET. L'euristica per giustificare questa scelta è il comportamento di un browser Web, che impacchetta i parametri nella stringa di query quando viene inviato un modulo con l'azione get. Funziona, è senza stato, il browser sta ancora seguendo un link contenuto nello stato dell'applicazione.

Se non si sta descrivendo lo stato dell'applicazione con una rappresentazione html, UriTemplates rappresenta un approccio ragionevole alla rappresentazione del collegamento. È possibile documentare i punti di contatto sui parametri come parte della definizione della relazione di collegamento.