7 best practice per dare un nome ai tuoi endpoint API
Pianifica in anticipo la denominazione della tua API e attieniti a ciò che funziona meglio.
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 in modo efficace tramite i suoi endpoint. Semplifica l'accesso degli utenti 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 includendo il metodo di richiesta e l'URL, ad esempio:
GET https://example.com/books/authorsDare un nome è difficile, che si tratti di endpoint API, dispositivi hardware in rete o funzioni e variabili. Dovresti conoscere alcune best practice che puoi utilizzare per garantire che i tuoi endpoint API siano una risorsa.
1. Usa una barra in avanti
Utilizza sempre le barre per separare le risorse URI. Le barre aiutano anche a mostrare la gerarchia delle risorse. Quanto segue è un esempio:
https://example.com/books/authors2. Usa sostantivi, non verbi
Dovresti usare solo nomi per nominare una risorsa. I sostantivi descrivono a cosa serve una risorsa in contrapposizione a un verbo che descrive ciò che fa una risorsa. Ecco un esempio di un modo positivo e negativo per denominare gli endpoint API.
Nome errato:
https://example.com/api/getBooksBuona denominazione:
http://example.com/api/books3. Usa nomi plurali, non singolari
Dovresti sempre denominare gli endpoint API con sostantivi plurali. Ciò indica a un utente che è presente più di una risorsa sul server. L'utilizzo di un sostantivo singolare può confondere l'utente facendogli credere che esista una sola risorsa.
Nome errato:
https://example.com/api/book/3Buona denominazione:
http://example.com/api/books/34. Usa lettere minuscole
Dovresti digitare tutti gli URL in minuscolo. Ciò include gli URL degli endpoint API. Ecco un esempio:
Nome errato:
http://example.com/api/Books/3Buona denominazione:
http://example.com/api/books/35. Usa i trattini per separare le parole
Usa i trattini per separare le parole combinate. I trattini danno luogo a frasi più leggibili rispetto al caso cammello o ai caratteri di sottolineatura. Sono anche migliori per scopi SEO.
Nome errato:
https://example.com/api/books/33/front_coverBuona denominazione:
https://example.com/api/books/33/front-cover6. Non aggiungere estensioni di file
Non è necessario aggiungere un'estensione di file agli endpoint API. Anche se non influisce sull'output, un'estensione rende più difficile leggere la risorsa. Inoltre rende la risorsa meno flessibile, interrompendola se l'estensione cambia in futuro.
Nome errato:
https://example.com/api/books.xmlBuona denominazione:
https://example.com/api/books7. Includere il controllo delle versioni
Dovresti sempre denominare gli endpoint API in base alla versione. Questo è importante se stai apportando modifiche importanti all'API. Aiuta a distinguere tra due o più versioni API da cui proviene la risorsa. È possibile indicare la versione all'inizio dell'endpoint.
Per esempio:
https://example.com/api/v3/booksPerché 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 degli endpoint API determinano le prestazioni della tua API.
Assicurati di utilizzare le best practice per creare endpoint API efficienti.