tutorial - ¿Hay alguna guía de convención de nombres para las API REST?
rest api tutorial español (10)
''UserId'' es totalmente el enfoque equivocado. El enfoque Verb (Métodos HTTP) y Noun es lo que Roy Fielding significó para la arquitectura REST . Los sustantivos son:
- Una colección de cosas
- Una cosa
Una buena convención de nombres 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 hacer un seguimiento de dónde ha puesto la ''s'' y dónde no. Además de la mitad del planeta (asiáticos para empezar) habla idiomas sin plurales explícitos, por lo que la URL es menos amigable para ellos.
Al crear API REST, ¿existen directrices o estándares de facto para las convenciones de nomenclatura dentro de la API (por ejemplo, componentes de ruta de extremo de URL, parámetros de cadena de consulta)? ¿Los gorros de camello son la norma o los subrayados? ¿otros?
Por ejemplo:
api.service.com/helloWorld/userId/x
o
api.service.com/hello_world/user_id/x
Nota: No se trata del diseño de la API RESTful, sino de las pautas de la convención de nomenclatura que se utilizarán para los componentes de la ruta eventual y / o los parámetros de cadena de consulta utilizados.
Cualquier guía 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 debe verse así (ignorando los problemas de diseño que haya solicitado :-))
api.service.com/hello-world/user-id/x
Diría que es preferible usar el menor número posible de caracteres especiales en las URL REST. Uno de los beneficios de REST es que hace que la "interfaz" para 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 ningún estándar duro sobre REST.
Además, creo que Gandalf tiene razón, por lo general es más limpio en REST no usar los parámetros de la cadena de consulta, sino que crea rutas que definen a qué recursos desea acceder.
La API REST para Dropbox , Twitter , Servicios web de Google y Facebook utiliza subrayados.
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.
Mire de cerca los URI para recursos web ordinarios. Esas son tu plantilla. Piensa en árboles de directorios; use nombres simples de archivos y directorios similares a los de Linux.
HelloWorld no es una clase de recursos realmente buena. No parece ser una "cosa". Puede ser, pero no es muy similar a un sustantivo. Un greeting es una cosa.
user-id puede ser un sustantivo que estás buscando. Sin embargo, es dudoso que el resultado de su solicitud sea solo un user_id. Es mucho más probable que el resultado de la solicitud sea un Usuario. Por lo tanto, el user es 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 nominal: una ruta a través de una jerarquía (o taxonomía, o directorio). Utilice los sustantivos más simples posibles, evitando frases nominales si es posible.
En general, las frases sustantivas compuestas generalmente significan otro paso en su jerarquía. Entonces no tiene /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 objetivo es proporcionar una ruta de navegación entre los recursos.
No creo que el camello sea el problema en ese ejemplo, pero me imagino que una convención de nomenclatura más REST para el ejemplo anterior sería:
api.service.com/helloWorld/userId/x
en lugar de hacer que userId sea un parámetro de consulta (que es perfectamente legal), mi ejemplo denota ese recurso en, IMO, de una manera más RESTful.
No. REST no tiene nada que ver con las convenciones de nomenclatura 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
Si autenticas a tus clientes con Oauth2, creo que necesitarás subrayado para al menos dos de tus nombres de parámetros:
- Identificación del cliente
- client_secret
He utilizado 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 parametros de Oauth son snake_case, mientras que otros params no lo están.
Tengo una lista de directrices en http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html que hemos utilizado en prod. Las pautas son siempre discutibles ... Creo que la coherencia es a veces más importante que hacer las cosas perfectas (si es que existe).