¿Existen pautas de convención de nomenclatura para las API REST? [cerrado]

Al crear API REST, ¿existen pautas o estándares de facto para las convenciones de nomenclatura dentro de la API (por ejemplo: componentes de ruta de punto final de URL, parámetros de cadena de consulta)? ¿Son los gorros de camello la norma o los guiones bajos? ¿otros?

Por ejemplo:

api.service.com/helloWorld/userId/x

o

api.service.com/hello_world/user_id/x

Nota: Esta no es una cuestión de diseño de API RESTful, sino de las pautas de la convención de nomenclatura que se utilizarán para los componentes de ruta eventuales y / o los parámetros de cadena de consulta utilizados.

Cualquier pauta sería apreciada.

Creo que deberías evitar las gorras de camello. La norma es usar letras minúsculas. También evitaría guiones bajos y usar guiones en su lugar

Por lo tanto, su URL debería tener este aspecto (ignorando los problemas de diseño que solicitó :-))

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

La API REST para Dropbox , Twitter , Google Web Services y Facebook usa guiones bajos.

Mire de cerca los URI para recursos web comunes. Esas son tu plantilla. Piense en los árboles de directorios; use archivos simples de Linux y nombres de directorio.

HelloWorldNo es una muy buena clase de recursos. No parece ser una "cosa". Puede ser, pero no es muy parecido a un nombre. A greetinges una cosa.

user-idpodría ser un sustantivo que estás buscando. Sin embargo, es dudoso que el resultado de su solicitud sea solo un ID de usuario. Es mucho más probable que el resultado de la solicitud sea un Usuario. Por lo tanto, useres el sustantivo que estás buscando

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

Tiene sentido para mi. Concéntrese en hacer que su solicitud REST sea una especie de frase sustantiva: una ruta a través de una jerarquía (o taxonomía o directorio). Use los sustantivos más simples posibles, evitando frases nominales si es posible.

En general, las frases con nombres compuestos generalmente significan otro paso en su jerarquía. Entonces no tienes /hello-world/user/y /hello-universe/user/. Tienes /hello/world/user/y hello/universe/user/. O posiblemente /world/hello/user/y /universe/hello/user/.

El punto es proporcionar una ruta de navegación entre los recursos.

'UserId' es totalmente el enfoque equivocado. El enfoque verbal (métodos HTTP) y sustantivo es lo que Roy Fielding significó para la arquitectura REST . Los sustantivos son:

1. Una colección de cosas
2. Una cosa

Una buena convención de nomenclatura es:

[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

Donde {media_type} es uno de: json, xml, rss, pdf, png, incluso html.

Es posible distinguir la colección agregando una 's' al final, como:

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

Pero esto significa que debe realizar un seguimiento de dónde ha colocado la 's' y dónde no. Además, la mitad del planeta (asiáticos para empezar) habla idiomas sin plurales explícitos, por lo que la URL es menos amigable para ellos.

No. REST no tiene nada que ver con las convenciones de nombres de URI. Si incluye estas convenciones como parte de su API, fuera de banda, en lugar de solo a través de hipertexto, entonces su API no es RESTful.

Para obtener más información, consulte http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Los nombres de dominio no distinguen entre mayúsculas y minúsculas, pero el resto del URI ciertamente puede serlo. Es un gran error suponer que los URI no distinguen entre mayúsculas y minúsculas.

Tengo una lista de pautas en http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html que hemos utilizado en prod. Las pautas siempre son debatibles ... Creo que la consistencia a veces es más importante que hacer que las cosas sean perfectas (si existe)

No creo que el caso del camello sea el problema en ese ejemplo, pero imagino que una convención de nomenclatura más RESTful para el ejemplo anterior sería:

api.service.com/helloWorld/userId/x

en lugar de convertir userId en un parámetro de consulta (que es perfectamente legal), mi ejemplo denota ese recurso en, IMO, de una manera más RESTful.

Si autentica a sus clientes con Oauth2, creo que necesitará subrayar al menos dos de sus nombres de parámetros:

• Identificación del cliente
• client_secret

He usado camelCase en mi API REST (aún no publicada). Mientras escribía la documentación de la API, he estado pensando en cambiar todo a snake_case, así que no tengo que explicar por qué los parámetros de Oauth son snake_case mientras que otros parámetros no lo son.

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

Diría que es preferible utilizar la menor cantidad de caracteres especiales posible en las URL REST. Uno de los beneficios de REST es que hace que la "interfaz" de un servicio sea fácil de leer. El caso Camel o el caso Pascal probablemente sea bueno para los nombres de los recursos (Usuarios o usuarios). No creo que haya realmente estándares estrictos en torno a REST.

Además, creo que Gandalf tiene razón, por lo general es más limpio en REST no usar parámetros de cadena de consulta, sino crear rutas que definan con qué recursos desea lidiar.

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