Convenzioni API RESTful

REST non si preoccupa della progettazione di URI. Per quanto riguarda REST, il cliente dovrebbe considerare l'URI come opaco. (Confrontalo con le intestazioni di cache - REST si preoccupa molto di assicurare che i componenti dell'intermediario possano partecipare correttamente al lavoro svolto.)

I have an API that generates a resource randomly when requested.

Questa è un'osservazione piuttosto particolare nel contesto di REST. Resource e representation sono termini importanti in REST e sono non intercambiabili.

Quello che mi aspetto che tu intenda è che la tua API include una risorsa che genera una rappresentazione casuale quando richiesto. Qualcosa come un generatore UUID ?

Poiché REST non esprime un'opinione sulla grafia dell'URI, è necessario ricorrere alle linee guida sulla progettazione dell'URI locale. Questi normalmente raccomandano che le risorse siano identificate dai nomi e che i segmenti del percorso esprimano la gerarchia.

/generators/random

"/ generatori" va bene, poiché suggerisce di identificare una risorsa che fa parte di una raccolta. "casuale", essendo un aggettivo, non è così buono. Il prossimo passo utile è probabilmente chiedere "random what?" Indovinando dal primo dei tuoi tentativi, queste potrebbero essere scelte ragionevoli

/generators/randomImage
/generators/randomPNG
/generators/image?random
/generators/png?random

Parte del punto di REST è che le implementazioni possono essere disaccoppiate dai servizi - la rappresentazione di una risorsa prodotta dal server di origine potrebbe essere caricata direttamente dal file system, oppure estratta direttamente da un archivio di valori chiave o prodotta da invocare una funzione o delegare il lavoro a un altro endpoint. Quindi probabilmente stai meglio identificando le tue risorse con cosa invece di come.

Quindi queste scelte sono molto migliori, perché esprimono meglio la rappresentazione (che è una rappresentazione di un'immagine, non una rappresentazione di un generatore di immagini casuali).

/images/random
/images/pngs/random

Should I place all my resources in a root like /api to differentiate them from web pages?

Forse. REST non si cura dell'ortografia. I clienti dovrebbero semplicemente seguire tutti i link che dai loro, quindi l'importante è assicurarsi che i tuoi segnalibri pubblicati siano ragionevoli. Alcuni servizi utilizzano un host diverso per distinguere le risorse API dalle risorse del documento; ma molti usano un segmento di percorso prefisso come suggerisci.

If the answer to 1 was similar to options A or B, what would exist at /generate?

Potrebbe non esserci nulla lì. Il fatto che esista una risorsa con un identificatore nel modello di un membro di una raccolta non implica in alcun modo che vi sia anche una risorsa per la raccolta stessa. Se lo desideri, puoi tranquillamente 404 di richieste in tal senso; i clienti di una API REST dovrebbero navigare verso i segnalibri pubblicati e seguire i link - giocare ai giochi guess-the-uri è fuori dai limiti.

Nelle apis in cui la raccolta di risorse è destinata a essere modificata dal client, un modello comune sarebbe avere un endpoint POST identificato dall'URI di raccolta che consente al client di creare nuovi membri nella raccolta.

Shouldn't I prefer something that conveys that it is generated randomly and requesting it again might not give the same result?

Le intestazioni di cache, piuttosto che l'URI, vengono utilizzate dai componenti REST per determinare se una rappresentazione precedentemente recuperata è ancora valida.

Il pubblico con lo spelling URI è puramente umano.

I principi guida sono descritti in Cool URIs Do not Change ; vuoi continuare a mappare lo stesso URI allo stesso concept anche quando l'implementazione sottostante per la produzione delle modifiche di rappresentazione.

/images/flowers/flowerOfTheDay
/images/flowers/latest
/images/flowers/random

Quindi ciò che devi considerare nel tuo design è se la casualità dell'immagine è fondamentale per il concetto?

REST relies instead on the author choosing a resource identifier that best fits the nature of the concept being identified.