Un'API RESTful dovrebbe essere in grado di restituire file o solo una posizione

Questo mi ha sconcertato per un po '.

Ad esempio, abbiamo un'API REST che fornisce contenuti di base a un sistema, consumando e producendo JSON. A questo endpoint produce un URL per un'immagine e una descrizione e si trova così: // localhost / myApi / pictures / 1

{
    id: 1,
    description: "This is a pretty picture of a daisy",
    URL: <OUR URL>
}

Ora OUR_URL dovrebbe puntare a una posizione sull'API, ad esempio // localhost / myApi / files / pictures / 1 che restituisce un JPG (l'applicazione dietro l'API legge il contenuto fisico del file e lo trasmette nuovamente al client ). Questo è ovviamente diverso dal resto dell'API che sta producendo risposte JSON e ci sarà un sovraccarico dalla lettura e dallo streaming del file reale.

In alternativa, OUR_URL dovrebbe puntare a un URL esterno all'ambito del servizio REST, quindi //localhost/files/pictures/1.jpg dove legge direttamente il file.

Quindi la domanda è:

Un'API RESTful dovrebbe essere in grado di restituire file o solo una posizione?

Un servizio RESTful dovrebbe fornire risorse agli utenti dell'API. Le risorse possono avere vari formati, che vanno da JSON o XML a JPEG e HTML.

Non c'è nemmeno un requisito, o addirittura un'aspettativa, che una singola API offra solo risorse di un singolo formato. Non c'è nulla di sbagliato nel servire un documento JSON sull'URI /myApi/pictures/1e un file JPEG dall'URI /myApi/files/pictures/1.
In un caso più estremo, è anche possibile servire sia la descrizione JSON che il file JPEG dallo stesso URL, a seconda del formato richiesto dal richiedente.

Un problema che avrai nel restituire gli URI è che un semplice vecchio file server non può fare sicurezza. Quindi, se hai bisogno di fare qualsiasi tipo di limitazione su chi può accedere a un file, allora dovrai essere in grado di restituirlo direttamente nell'API REST (o no, se l'utente non ha diritti, il file è non nello stato corretto, ecc.).

Altrimenti, restituire il semplice vecchio URI e lasciarlo andare a una CDN dedicata ha molti vantaggi in termini di provisioning, semplicità e scalabilità, supponendo che sia tutto ciò che devi fare.