Esistono linee guida sulla convenzione di denominazione per le API REST? [chiuso]

Quando si creano API REST, esistono delle linee guida o degli standard defacto per le convenzioni di denominazione all'interno dell'API (ad esempio: componenti del percorso dell'endpoint URL, parametri di querystring)? I cappelli dei cammelli sono la norma o i trattini bassi? altri?

Per esempio:

api.service.com/helloWorld/userId/x

o

api.service.com/hello_world/user_id/x

Nota: non si tratta della progettazione dell'API RESTful, ma piuttosto delle linee guida della convenzione di denominazione da utilizzare per i componenti del percorso e / o i parametri della stringa di query utilizzati.

Qualsiasi linea guida sarebbe apprezzata.

Penso che dovresti evitare i cappelli di cammello. La norma è usare lettere minuscole. Vorrei anche evitare i trattini bassi e utilizzare invece i trattini

Quindi il tuo URL dovrebbe assomigliare a questo (ignorando i problemi di progettazione come richiesto :-))

api.service.com/hello-world/user-id/x

L'API REST per Dropbox , Twitter , Google Web Services e Facebook utilizza tutti i trattini bassi.

Osserva attentamente gli URI per le normali risorse web. Quelli sono il tuo modello. Pensa agli alberi delle directory; usa semplici nomi di file e directory simili a Linux.

HelloWorldnon è davvero una buona classe di risorse. Non sembra essere una "cosa". Potrebbe essere, ma non è molto simile al nome. A greetingè una cosa.

user-idpotrebbe essere un sostantivo che stai recuperando. È dubbio, tuttavia, che il risultato della tua richiesta sia solo un user_id. È molto più probabile che il risultato della richiesta sia un Utente. Pertanto, userè il nome che stai recuperando

www.example.com/greeting/user/x/

Ha senso per me. Concentrati sul rendere la tua richiesta REST una specie di frase del sostantivo - un percorso attraverso una gerarchia (o tassonomia o directory). Usa i nomi più semplici possibili, se possibile evitando frasi di nome.

Generalmente, le frasi di nomi composti di solito significano un altro passo nella tua gerarchia. Quindi non hai /hello-world/user/e /hello-universe/user/. Hai /hello/world/user/e hello/universe/user/. O forse /world/hello/user/e /universe/hello/user/.

Il punto è fornire un percorso di navigazione tra le risorse.

"UserId" è totalmente l'approccio sbagliato. L'approccio Verb (metodi HTTP) e Noun è ciò che Roy Fielding ha significato per l'architettura REST . I nomi sono:

1. Una raccolta di cose
2. Una cosa

Una buona convenzione di denominazione è:

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

Dove {media_type} è uno di: json, xml, rss, pdf, png, persino html.

È possibile distinguere la collezione aggiungendo una 's' alla fine, come:

'users.json' *collection of things*
'user/id_value.json' *single thing*

Ma questo significa che devi tenere traccia di dove hai messo la 's' e dove non l'hai fatto. Inoltre metà del pianeta (asiatici per cominciare) parla lingue senza plurali espliciti, quindi l'URL è meno amichevole con loro.

No. REST non ha nulla a che fare con le convenzioni di denominazione URI. Se includi queste convenzioni come parte dell'API, fuori banda, anziché solo tramite ipertesto, l'API non è RESTful.

Per ulteriori informazioni, consultare http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

I nomi di dominio non fanno distinzione tra maiuscole e minuscole, ma il resto dell'URI può sicuramente esserlo. È un grosso errore supporre che gli URI non facciano distinzione tra maiuscole e minuscole.

Ho un elenco di linee guida su http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html che abbiamo usato in prod. Le linee guida sono sempre discutibili ... Penso che la coerenza a volte sia più importante che ottenere le cose perfette (se esiste una cosa del genere).

Non penso che il caso del cammello sia il problema in questo esempio, ma immagino che una convenzione di denominazione più RESTful per l'esempio sopra sarebbe:

api.service.com/helloWorld/userId/x

piuttosto che rendere userId un parametro di query (che è perfettamente legale) il mio esempio indica quella risorsa, IMO, in un modo più RESTful.

Se autentichi i tuoi clienti con Oauth2, penso che avrai bisogno di sottolineatura per almeno due dei nomi dei tuoi parametri:

• Identificativo cliente
• client_secret

Ho usato camelCase nella mia API REST (non ancora pubblicata). Durante la stesura della documentazione API ho pensato di cambiare tutto in snake_case, quindi non devo spiegare perché i parametri di Oauth sono snake_case mentre altri non lo sono.

Vedi: https://tools.ietf.org/html/rfc6749

Direi che è preferibile utilizzare il minor numero possibile di caratteri speciali negli URL REST. Uno dei vantaggi di REST è che rende l '"interfaccia" per un servizio di facile lettura. Il caso Camel o il caso Pascal è probabilmente buono per i nomi delle risorse (Utenti o utenti). Non credo che ci siano davvero degli standard rigidi nei confronti di REST.

Inoltre, penso che Gandalf abbia ragione, di solito in REST è più pulito non utilizzare i parametri della stringa di query, ma creare invece percorsi che definiscono le risorse con cui si desidera gestire.

http://api.example.com/HelloWorld/Users/12345/Order/3/etc