Assegnazione di un nome per un webservice REST

Ecco come appare di solito REST

GET www.example.com/service.svc/MAC - gets a list of all the MACs
GET www.example.com/service.svc/MAC?{property}={value} - search MACs by specified properties
POST www.example.com/service.svc/MAC - creates a new MAC
GET www.example.com/service.svc/MAC/{id} - gets the MAC with the specified id
PUT www.example.com/service.svc/MAC/{id} - updates the MAC with the specified id
DELETE www.example.com/service.svc/MAC/{id} - deletes the MAC with the specified id

Ci sono anche alcune operazioni meno usate: PUT /MAC sostituirebbe l'intera collezione di MAC, DELETE /MAC eliminerebbe tutto e POST /MAC/{id} creerebbe i sottitemi nel MAC, ma sembra che tu non voglia averne bisogno.

Quanto segue offre un set suggerito di linee guida per la denominazione URI per i servizi REST che hanno funzionato per me nella pratica.

Il libro RESTful Web Services RESTful Web Services definisce tre regole di base per la progettazione di URL che fungono da ottimo punto di partenza:

• Utilizza le variabili di percorso per codificare la gerarchia: / parent / child
• Inserisci i caratteri di punteggiatura nelle variabili del percorso per evitare di implicare una gerarchia in cui non esiste nessuno: / parent / child1; child2
• Utilizza le variabili di query per implicare input in un algoritmo, ad esempio: / search? q = jellyfish & start = 20

Altre linee guida includono:

• Gli URI dovrebbero idealmente non cambiare nel tempo.
• I servizi che offrono una risorsa identificabile in modo univoco tramite una chiave devono utilizzare la notazione di base (ad esempio / account / (accountid))
• I servizi che offrono funzionalità di ricerca / filtraggio opzionali dovrebbero utilizzare il parametro di ricerca? key1 = value & key2 = notazione del valore (ad es. / strumenti? ticker = FT)
• I servizi che prevedono argomenti obbligatori su GET dovrebbero averli come variabili di percorso (ad es. / accounthistory / (fromdate) / (todate)
• Tutti i nomi dei servizi di restrizione devono utilizzare nomi di maiuscole e minuscole (ad esempio / cliente)
• Gli elementi dell'URI devono essere associati alle entità aziendali e la mappatura deve essere coerente. Ad esempio un'entità aziendale denominata contentpartner dovrebbe essere coerentemente denominata contentpartner (s) in tutti gli URI (piuttosto che un mix di partner, cp ecc.). Un buon punto di partenza sarebbe il nome dell'oggetto dominio.
• I parametri che non definiscono una risorsa ma la qualificano (ad esempio la localizzazione che alimenta le traduzioni dei dati) non dovrebbero far parte del normale spazio URI. Prendi in considerazione l'utilizzo di intestazioni o parametri di query facoltativi per questi
• Usa nomi, non i verbi. Il potere di REST passa attraverso il fatto che esiste un set di verbi limitato (operazioni) combinato con un grande insieme di nomi (o risorse). Di conseguenza, il modo in cui questi nomi sono costruiti è di grande importanza.
• Evita i suffissi. Quando si progettano gli ISU è fondamentale che si riferiscano alla cosa su cui si sta operando piuttosto che all'operazione che viene eseguita. In secondo luogo, il cliente è interessato alla risorsa, non all'implementazione del software server che alimenta il servizio. È auspicabile evitare suffissi come .jsp o .aspx.
• Utilizza Accetta intestazione per la negoziazione del contenuto
• Keep It Intuitive. Gli URI dovrebbero essere leggibili o ipotetici. Il modo più semplice per farlo è costruire una gerarchia URI, raggruppando elementi correlati. Tali modelli di categoria e sottocategoria sono molto facili da capire.

Il modo REST per elencare tutti i MAC è:

GET www.foobar.com/service.svc/MAC

Perché? Bene, perché è una convenzione e la gente si aspetta che il servizio REST si comporti in questo modo.

Se vuoi saperne di più su questo argomento, controlla come il routing RESTful è fatto in Rails .

Ho pubblicato una serie di linee guida qui: link

Questi sono usati efficacemente, dove lavoro.

AGGIORNAMENTO - Ho incollato il contenuto in un'altra risposta ....

Robert