Estoy haciendo un API Rest, y quería usar las especificaciones lo más correctamente posible.
He estado revisando las especificaciones de respuesta JSON para estructurarlas todas de la misma forma, ya que estoy haciendo microservicios y quiero que todos tengan la misma estructura.
La cosa es que implementando los servicios no termina de quedarme claro el código de respuesta que tengo que enviar en cada caso. Os lo expongo, para ver como lo tratáis vosotros:
1º GET, PUT, DELETE "/entidades/3": La entidad "3" no existe. Si el recurso no existe, ¿se devolvería 404?
2º POST "/entidades", PUT "/entidades/3": Los datos enviados no son válidos para almacenarlos en la entidad, por lo que debe devolver los errores producidos ¿con qué código de estado HTTP?.
3º GET "/entidades/3/calcularDato?parametroCalculo=69". Sin embargo en la petición se está enviando "/entidades/calcularDato" sin parámetro. ¿Con que código se le indica que falta query params?. ¿o pondríais "entidades/3/calcularDato/69"?. Al ser un cálculo y no formar parte del recurso... lo he puesto como query param.
4º GET "/entidades/3/calcularDato?parametroCalculo=formatoMalo". Es decir, el parámetro debe ser numérico, pero no lo es.
Es que estoy comenzando con microservicios y APIs rest... y aún tengo algunas lagunas en cuanto a como devolver directamente los códigos de estado, como formar las urls... etc.
Hola Francisco José, no sé si yo lo estoy haciendo "de libro", pero lo que hago es:
1.- Devuelvo un 404 si la entidad no existe
2, 3 y 4.- Si los parámetros no son válidos, bien porque se esperaba un número y ha llegado otra cosa, o bien porque faltan parámetros, yo devuelvo un 400 (Bad request). Para mi es suficientemente explicativo de que la petición no es correcta
así en general, al tratarse todos de errores por parte del usuario sería un 4xx, ya es cuestión de cual es el que más se aproxima semánticamente pero yo devolvería un 400 Bad Request https://refly.xyz/http/400_bad_request.
Lo que si me llama la atención es el nombre del recurso calcularDato, que representa?
@David, respecto al calcularDato, es posible que no haya formado bien el nombre del servicio y no sea coherente. Aprovecho para preguntarlo también...
Básicamente cada entidad tiene una fórmula propia, que recibiendo número tiene que devolver otro. Así que necesito exponer un servicio que dado el código de una entidad y un número devuelva el resultado configurado en el servidor para esa entidad.
¿Está mal formada la URL?, ¿hay alguna más estandar y coherente?.
Bueno, es complicado sin conocer el modelo. Pero ese resultado que vas a devolver debería ser un recurso y ese recurso debería tener un nombre y la url debería ser coherente.
Estoy haciendo un API Rest, y quería usar las especificaciones lo más correctamente posible.
He estado revisando las especificaciones de respuesta JSON para estructurarlas todas de la misma forma, ya que estoy haciendo microservicios y quiero que todos tengan la misma estructura.
La cosa es que implementando los servicios no termina de quedarme claro el código de respuesta que tengo que enviar en cada caso. Os lo expongo, para ver como lo tratáis vosotros:
1º GET, PUT, DELETE "/entidades/3": La entidad "3" no existe. Si el recurso no existe, ¿se devolvería 404?
2º POST "/entidades", PUT "/entidades/3": Los datos enviados no son válidos para almacenarlos en la entidad, por lo que debe devolver los errores producidos ¿con qué código de estado HTTP?.
3º GET "/entidades/3/calcularDato?parametroCalculo=69". Sin embargo en la petición se está enviando "/entidades/calcularDato" sin parámetro. ¿Con que código se le indica que falta query params?. ¿o pondríais "entidades/3/calcularDato/69"?. Al ser un cálculo y no formar parte del recurso... lo he puesto como query param.
4º GET "/entidades/3/calcularDato?parametroCalculo=formatoMalo". Es decir, el parámetro debe ser numérico, pero no lo es.
Es que estoy comenzando con microservicios y APIs rest... y aún tengo algunas lagunas en cuanto a como devolver directamente los códigos de estado, como formar las urls... etc.
Gracias por vuestro tiempo.
¡Un saludo!.
07/07/2015 12:37
1.- Devuelvo un 404 si la entidad no existe
2, 3 y 4.- Si los parámetros no son válidos, bien porque se esperaba un número y ha llegado otra cosa, o bien porque faltan parámetros, yo devuelvo un 400 (Bad request). Para mi es suficientemente explicativo de que la petición no es correcta
07/07/2015 12:06
así en general, al tratarse todos de errores por parte del usuario sería un 4xx, ya es cuestión de cual es el que más se aproxima semánticamente pero yo devolvería un 400 Bad Request https://refly.xyz/http/400_bad_request.
Lo que si me llama la atención es el nombre del recurso calcularDato, que representa?
Saludos,
07/07/2015 14:10
¡Gracias por las respuestas!.
Oído cocina, configuraré esos códigos.
@David, respecto al calcularDato, es posible que no haya formado bien el nombre del servicio y no sea coherente. Aprovecho para preguntarlo también...
Básicamente cada entidad tiene una fórmula propia, que recibiendo número tiene que devolver otro. Así que necesito exponer un servicio que dado el código de una entidad y un número devuelva el resultado configurado en el servidor para esa entidad.
¿Está mal formada la URL?, ¿hay alguna más estandar y coherente?.
De nuevo muchas gracias por las respuestas.
Un saludo.
07/07/2015 15:29
Saludos,