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


212

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.

Respuestas:


150

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

187
De acuerdo con RFC2616, solo el esquema y las partes de host de la URL no distinguen entre mayúsculas y minúsculas. El resto de la URL, es decir, la ruta y la consulta DEBEN distinguir entre mayúsculas y minúsculas. w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3
Darrel Miller

10
Daniel, tienes razón, gracias por señalarlo. Sin embargo, de hecho, generalmente esperamos que las URL ignoren los casos, especialmente la parte del nombre del recurso. No tendría sentido que userid & UserId se comporten de manera diferente (a menos que uno de ellos devuelva 404)
LiorH

18
@LiorH: ¿Por qué crees que "no tiene sentido" ser sensible a mayúsculas y minúsculas? Muchos otros contextos son sensibles a mayúsculas y minúsculas para un buen efecto. Hay algunos servicios web (por ejemplo, Amazon S3) que hacen cumplir las mayúsculas y minúsculas para los puntos finales de URL, y yo creo que es muy apropiado.
Hank

66
Los sistemas de archivos del servidor @Dennis Windows no distinguen entre mayúsculas y minúsculas por defecto, a menos que esté muy equivocado technet.microsoft.com/en-us/library/cc725747.aspx
samspot

55
@samspot ¡Buena! Pensé que Windows había ido directamente a los nombres de archivo sensibles a mayúsculas y minúsculas cuando crearon servidores. WOW, todavía estaban presionando SU camino por el mayor tiempo posible, es decir, "1 MicroSoft Way". ;-)
Dennis

87

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


24
Uno de los efectos secundarios de eso es que las 'palabras' subrayadas se mantienen enteras, juntas en los índices de búsqueda de Google. Los hyhenated se dividen en palabras separadas.
Dennis


11
Si bien la API de Google Maps utiliza guiones bajos, la Guía de estilo de Google requiere Camel Case. La API de Google+ y la API de búsqueda personalizada , entre otras, usan Camel Case.
Benjamin

2
Sin embargo, todavía usan '-' como separador de esas URL: P developers.google.com/custom-search/json-api/v1/reference/cse/… developers.google.com/+/best-practices dev.twitter. com / overview / case-studies Por otro lado, usan camelCase en los parámetros de consulta.
Mattias

1
Nadie sabe ...
Piotr Kula

84

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.


44
Mi pregunta es más sobre la convención de nomenclatura de los posibles nombres de ruta y / o parámetros de cadena de consulta, sean cuales sean. Estoy de acuerdo con sus recomendaciones de diseño, así que gracias, pero con esta pregunta solo estoy preguntando sobre las convenciones de nomenclatura.
jnorris el

1
Solo para tener en cuenta, no hay nada que le impida usar REST para recursos no jerárquicos. Las convenciones de nomenclatura de URI reales que usa son irrelevantes, solo use lo que crea que se ve bien y es fácil de analizar en el servidor. El cliente no debe saber nada sobre la generación de sus URI ya que debe enviar los URI a los recursos a través de hipertexto en sus respuestas.
aehlke

30

'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.


¿Qué se entiende con {var}? Si busco un usuario por nombre, por ejemplo ... / user / username / tomsawyer?
Hans-Peter Störr

1
Si tuviera tres variables (var) s llamadas x, y, z, entonces su URL se vería así: sub.domain.tld / x / value_of_x / y / value_of_y / z / value_of_z
Dennis

@hstoerr Solo para asegurarme de que estaba claro, la mayoría de los lenguajes de script usan algún tipo de 'sustitución de variables de corchetes'. Entonces {var} significa que alguna variable (su nombre) reside allí, y entonces el siguiente {valor} es donde está el valor de {var} antes. Ejemplo: sub.domain.tld / script / {var} / {value} .json [www.yelp.com/food_reviews/review_averages_higher_than/4.json] estaría tratando de obtener los resultados json de yelp.com para ver los alimentos que muestran un valor superior a 4.
Dennis

Esta es la mejor respuesta en mi opinión y felicitaciones por pensar internacionalmente.
beiller

14

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


44
Descansa ... todavía es bueno tener URLs bonitas.
HDave

1
De acuerdo con @HDave, está muy en el espíritu de REST tener URL que se comprendan fácilmente. Estás trabajando con URL, ¿por qué no quieres que sean tan fáciles de comprender como los nombres de variables y parámetros en tu código?
mahemoff

44
@mahemoff lo siento, este soy yo siendo súper pedante. Pero el aspecto de sus URL no tiene nada que ver con REST. Eso no significa que no sean algo bueno, solo son ortogonales a lo que REST describe. Es engañoso decir que REST se trata de estructurar las URL de esta manera, ya que lleva a las personas a describir las API de RPC como REST solo porque tienen URL legibles / estructuradas.
aehlke

55
En resumen, las URL atractivas son geniales y todos deberían tenerlas. Sin embargo, no tiene nada que ver con REST.
aehlke

1
@aehlke gracias por aclarar esto. El resto no se trata de estructuras de URL. No entiendo por qué es tan difícil de entender para la gente.
user1431072

9

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.



2

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.


Esta no es una cuestión de diseño de API RESTful, sino de las pautas de convención de nomenclatura que se utilizarán para los componentes de ruta eventuales y / o los parámetros de cadena de consulta utilizados. En su ejemplo, ¿deberían los componentes de la ruta estar en mayúsculas como ha usado, o subrayar?
jnorris el

Bueno, dado que en REST sus URL son sus interfaces, entonces es una especie de pregunta API. Si bien no creo que haya pautas específicas para su ejemplo, iría personalmente con el caso camel.
Gandalf

No debe usar parámetros de consulta para los recursos que desea almacenar en caché en cualquier nivel de la pila HTTP.
aehlke

@aehlke Todo lo contrario también es cierto. Si NO desea que los parámetros de consulta se almacenen en caché, use el estilo GET para los parámetros, ~ O ~ asegúrese de modificar / insertar encabezados anticaching para cualquier cosa que no desee almacenar en caché. Además, hay un encabezado que es un hash del objeto / página retirada, úselo para indicar cambios de cosas que SI desea guardar en caché, pero que se actualizan cuando hay ediciones.
Dennis

@aehlke Descubrí el almacenamiento en caché y lo agrego. Recuerdo una presentación de CodeCamp en la que una de las aceleraciones estaba haciendo todos estos encabezados, y luego cambiando el nombre del archivo y todas las referencias a él cuando cambiaba su contenido para que los prestatarios y los proxies ingresaran al servidor una versión más nueva después de un largo tiempo de caché. conjunto. Aquí están todos los detalles sangrientos: developers.google.com/speed/docs/best-practices/caching
Dennis

2

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


0

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

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.