API: entry point & versioning

[Marco De Paoli]

ciao a tutti,

voi come organizzate la API di un progetto django?

Mi trovo con un progetto django in cui avevo fatto spuntare un po' qua e un po' la varie API distribute nelle molteplici app del progetto

Per cui sono al momento disponibili varie chiamate con url tipo:

 "<nome-app>/api/<entry-point-specifico>"

Ma ora, all'aumentare del numero di chiamate, si sta creando obiettivamente un po' di confusione

Anche perché gli utilizzatori non raggionano "per-app"

Per loro sono le API del progetto. Punto. L'app che effettivamente le implementa è un dettaglio interno

Quindi ho idea di esporre un prefisso comune per tutte le API

Una cosa tipo:

 "<url-base-progetto>/api"

(Se proprio proprio dovesse esserci necessità mi riservo di introdurre dei sotto raggruppamenti)

Inoltre, dato che che farò questo lavoro, vorrei anche pensare ad un versioning sulle API

Finora tutte le API erano implicitamente in versione beta "0.1" e quindi mi sono permesso di cambiare abbastanza liberamente signature e formato della response

Ma da ora vorrei tutelare chi svilupperà utilizzando queste API per cui mi piacerebbe adottare uno schema di versioning

In questo modo posso mantenere retrocompatibilità e percorso di obsolescenza

Ecco quindi che gli url dovrebbero diventare tipo

"<url-base-progetto>/api/v1/"

Potendo quindi contare poi su

"<url-base-progetto>/api/v2/"

"<url-base-progetto>/api/v3/"

Devo finire di chiarirmi le idea

Ma nel frattempo... 

nessuno meglio della lista django può darmi suggerimenti/critiche/consigli/caso-d'uso etc. etc.!

Sparate pure liberamente, Grazie!

Marco

Ah, per la cronaca, sono su DRF

[Marco Beri]

Il giorno lun 21 gen 2019, 11:47 Marco De Paoli <depa...@gmail.com> ha scritto:

ciao a tutti,

voi come organizzate la API di un progetto django?

Ecco quindi che gli url dovrebbero diventare tipo

"<url-base-progetto>/api/v1/"

Potendo quindi contare poi su

"<url-base-progetto>/api/v2/"

"<url-base-progetto>/api/v3/"

Noi facciamo così. Anche se sinora non abbiamo mai raggiunto v2 😂

L'eventuale app viene dopo la versione. 

Poi si apre la questione del formato del dato. Se invece di json voglio xml, vado di querystring? Io risponderei sì, ma mica sono sicuro sia giusto...

Ciao. 

Marco.

Devo finire di chiarirmi le idea

Ma nel frattempo... 

nessuno meglio della lista django può darmi suggerimenti/critiche/consigli/caso-d'uso etc. etc.!

Sparate pure liberamente, Grazie!

Marco

Ah, per la cronaca, sono su DRF

--
Hai ricevuto questo messaggio perché sei iscritto al gruppo "Django-it" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a django-it+...@googlegroups.com.
Per postare in questo gruppo, invia un'email a djan...@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/django-it.
Per altre opzioni visita https://groups.google.com/d/optout.

[Marco De Paoli]

ciao Marco!

Il giorno lun 21 gen 2019 alle ore 11:53 Marco Beri <marc...@gmail.com> ha scritto:

Il giorno lun 21 gen 2019, 11:47 Marco De Paoli <depa...@gmail.com> ha scritto:

ciao a tutti,

voi come organizzate la API di un progetto django?

Ecco quindi che gli url dovrebbero diventare tipo

"<url-base-progetto>/api/v1/"

Potendo quindi contare poi su

"<url-base-progetto>/api/v2/"

"<url-base-progetto>/api/v3/"

Noi facciamo così.

ok!

Anche se sinora non abbiamo mai raggiunto v2 😂

quindi, se capisco bene, cercate di essere retro-compatibili...

cioè si va solo di: nuovi entry-point, nuovi filtri, o nuovi campi nella response

... beh, è tendenzialmente ragionevole

a me è giusto capitato qualche raro caso in cui non voglio più restituire un campo nella response oppure voglio invalidare un intero entry-point (non devono più usarlo) da cui la mia domanda

Anche se capisco che esporre un intera v2 possa essere un over-kill

L'eventuale app viene dopo la versione. 

ok!

 

Poi si apre la questione del formato del dato. Se invece di json voglio xml, vado di querystring? Io risponderei sì, ma mica sono sicuro sia giusto...

ok, anche a me sembra giusto

anche perchè posso sempre dargli la response nel formato che vogliono purché json ;-)

 

Ciao. 

Marco.

Grazie!

M.

... ma scusa un attimo... hai mica fatto top-quoting? ;-) :-D

[Raffaele Salmaso]

On Mon, Jan 21, 2019 at 11:47 AM Marco De Paoli <depa...@gmail.com> wrote:

ciao a tutti, voi come organizzate la API di un progetto django? 

"<url-base-progetto>/api/v1/"

Potendo quindi contare poi su

"<url-base-progetto>/api/v2/"

"<url-base-progetto>/api/v3/"

Yes, faccio anch'io così

PS: preferisco passare tutto dalla url (versione, formato, ecc) invece che attraverso gli header, molto più semplice da gestire/condividere le url (almeno le GET :D)

--

| Raffaele Salmaso
| https://salmaso.org
| https://bitbucket.org/rsalmaso
| https://github.com/rsalmaso

[Riccardo Magliocchetti]

Il 21/01/19 11:53, Marco Beri ha scritto:

> Il giorno lun 21 gen 2019, 11:47 Marco De Paoli <depa...@gmail.com> ha
> scritto:
>
>> ciao a tutti,
>> voi come organizzate la API di un progetto django?
>>
>> Ecco quindi che gli url dovrebbero diventare tipo
>> "<url-base-progetto>/api/v1/"
>>
>> Potendo quindi contare poi su
>> "<url-base-progetto>/api/v2/"
>> "<url-base-progetto>/api/v3/"
>
> Noi facciamo così. Anche se sinora non abbiamo mai raggiunto v2 😂

La documentazione di DRF ha un articolo sul versioning:
https://www.django-rest-framework.org/api-guide/versioning/


--
Riccardo Magliocchetti
@rmistaken

http://menodizero.it

[Marco De Paoli]

Il giorno lun 21 gen 2019 alle ore 12:01 Raffaele Salmaso <raff...@salmaso.org> ha scritto:

On Mon, Jan 21, 2019 at 11:47 AM Marco De Paoli <depa...@gmail.com> wrote:

ciao a tutti, voi come organizzate la API di un progetto django? 

"<url-base-progetto>/api/v1/"

Potendo quindi contare poi su

"<url-base-progetto>/api/v2/"

"<url-base-progetto>/api/v3/"

Yes, faccio anch'io così

PS: preferisco passare tutto dalla url (versione, formato, ecc) invece che attraverso gli header, molto più semplice da gestire/condividere le url (almeno le GET :D)

giusto, concordo 

avevo dimenticato di dire che tendenzialmente uso DRF (tranne in pochi casi in cui ho una view diretta)

quindi potrei usare una cosa del genere:

https://www.django-rest-framework.org/api-guide/versioning/#urlpathversioning

grazie,

M.

[Marco De Paoli]

ciao Riccardo

sì, grazie, infatti

... mi pare di capire che il URLPathVersioning è il più adatto nel mio caso ...

M. 

[Marco Beri]

Il giorno lun 21 gen 2019, 12:00 Marco De Paoli <depa...@gmail.com> ha scritto:

... ma scusa un attimo... hai mica fatto top-quoting? ;-) :-D

Non mi pare. 

Al limite non ho cancellato il resto del messaggio... 😉

Ciao.

Marco.

[Marco De Paoli]

giusto giusto

ho provato a scatenare un beri-flame :-)

ma mancano effettivamente gli estremi 

M.