7 best practice per assegnare un nome ai tuoi endpoint API

Un endpoint API è un punto di connessione tra due programmi software. Le API hanno endpoint per ogni risorsa. Gli endpoint specificano la posizione esatta di una risorsa sul server.

Quando un’applicazione client richiede informazioni dal server, passa attraverso l’API. Che quindi accede alla richiesta ed elabora una risposta dal server. L’API trasferisce quindi le informazioni richieste dall’endpoint all’applicazione.

La tua API è efficiente se può comunicare efficacemente tramite i suoi endpoint. Rende più facile per gli utenti l’accesso alle risorse, migliorando l’esperienza dell’utente.

Come funziona un endpoint API?

I sistemi integrati comunicano tramite API. Un sistema invia una richiesta all’API, utilizzando un formato come SOAP o REST. Il server riceve le richieste e trasferisce la risposta all’API. La posizione della risorsa richiesta è l’endpoint.

Prima che un endpoint elabori una richiesta, il client deve fornire un URL, intestazioni e un corpo. Le intestazioni contengono metadati su una richiesta e il corpo dettaglia i dati inviati al server. Un server può anche connettersi a un database a cui possono accedere i metodi API.

Gli endpoint API in genere funzionano con metodi HTTP come GET, DELETE, PATCH o POST. I metodi determinano come utilizzare un endpoint. Quando un client invia una richiesta, deve formularla per includere il metodo della richiesta e l’URL, ad esempio:

GET https://example.com/books/authors

La denominazione è difficile, che si tratti di endpoint API, dispositivi hardware in rete o funzioni e variabili. Dovresti conoscere alcune best practice che puoi utilizzare per assicurarti che i tuoi endpoint API siano una risorsa.

1. Usa una barra in avanti

Usa sempre le barre per separare le risorse URI. Le barre aiutano anche a mostrare la gerarchia delle risorse. Quanto segue è un esempio:

2. Usa sostantivi, non verbi

Dovresti usare solo sostantivi per denominare una risorsa. I sostantivi descrivono a cosa serve una risorsa al contrario di un verbo che descrive cosa fa una risorsa. Ecco un esempio di un modo buono e uno cattivo per denominare gli endpoint API.

Buona denominazione:

Cattiva denominazione:

http://example.com/api/books

3. Usa sostantivi plurali, non singolari

Dovresti sempre nominare i tuoi endpoint API con sostantivi plurali. Ciò indica a un utente che è presente più di una risorsa sul server. L’uso di un nome singolare può indurre l’utente a pensare che esista una sola risorsa.

Buona denominazione:

Cattiva denominazione:

http://example.com/api/books/3

4. Usa lettere minuscole

Dovresti digitare tutti gli URL in minuscolo. Ciò include gli URL dell’endpoint API. Ecco un esempio:

Buona denominazione:

http://example.com/api/Books/3

Cattiva denominazione:

http://example.com/api/books/3

5. Usa i trattini per separare le parole

Usa i trattini per separare le parole combinate. I trattini risultano in frasi più leggibili rispetto a camel case o underscore. Sono anche migliori per scopi SEO.

Buona denominazione:

Cattiva denominazione:

6. Non aggiungere estensioni di file

Non è necessario aggiungere un’estensione di file agli endpoint API. Sebbene non influisca sull’output, un’estensione rende più difficile la lettura della risorsa. Rende anche la risorsa meno flessibile, interrompendola se l’estensione cambia in futuro.

Buona denominazione:

Cattiva denominazione:

7. Includi il controllo delle versioni

Dovresti sempre denominare i tuoi endpoint API in base alla versione. Questo è importante se stai apportando modifiche importanti all’API. Aiuta a distinguere tra due o più versioni dell’API da cui proviene la risorsa. È possibile indicare la versione all’inizio dell’endpoint.

Per esempio:

Perché prendere in considerazione le best practice API?

Le API sono diventate la spina dorsale della programmazione moderna. Migliorano la collaborazione, incoraggiano l’innovazione e migliorano la sicurezza delle applicazioni.

Sia che si utilizzino nuovi strumenti o si gestiscano quelli esistenti, le API semplificano il processo. Quindi è essenziale disporre di endpoint che migliorino l’esperienza dell’utente. La denominazione e la struttura dei tuoi endpoint API determinano le prestazioni della tua API.

Assicurati di utilizzare le best practice per creare endpoint API efficienti.