examples error ejemplo codigos code api validation rest request http-status-code-400

error - linkedin api key



API RESTful: comportamiento correcto cuando se pasan parámetros espurios/no solicitados en la solicitud (6)

Estamos desarrollando una api RESTful que acepta parámetros de consulta en la solicitud en forma de datos codificados JSON.

Nos preguntábamos cuál es el comportamiento correcto cuando se pasan los parámetros no solicitados / no esperados junto con los requeridos.

Por ejemplo, podemos requerir que una solicitud PUT en un punto final dado tenga que proporcionar exactamente dos valores respectivamente para el nombre y el apellido de las claves:

{ "name": "Jeff", "surname": "Atwood" }

¿Qué sucede si también se pasa una clave espuria, como el color en el siguiente ejemplo?

{ "name": "Jeff", "surname": "Atwood", "color": "red" }

El valor para el color no se espera, ni se documenta.

¿Debemos ignorarlo o rechazar la solicitud con un error de estado BAD_REQUEST 400?

Podemos afirmar que la solicitud es incorrecta porque no se ajusta a la documentación. Y probablemente el usuario de la API debería ser advertido al respecto (ella pasó el valor, esperará algo para eso).

Pero también podemos afirmar que la solicitud puede aceptarse porque, como se proporcionan todos los parámetros necesarios, se puede cumplir.

Después de haber usado las API REST de numerosos proveedores a lo largo de los años, permítame darle una perspectiva de "usuarios".

Muchas veces la documentación es simplemente mala o desactualizada. Tal vez haya cambiado el nombre de un parámetro, tal vez aplique una cubierta exacta a los nombres de las propiedades, tal vez haya usado la fuente incorrecta en su documentación y tenga una I que se ve exactamente como una I , sí, esas son letras diferentes.

No lo ignores. En su lugar, envíe un mensaje de error que indique el nombre de la propiedad con un mensaje fácil de entender. Por ejemplo, " Nombre de propiedad desconocido: color ".

Esta pequeña cosa ayudará en gran medida a limitar las solicitudes de soporte en relación con el consumo de su API.

Si simplemente ignora los parámetros, entonces un desarrollador podría pensar que se están pasando valores válidos mientras cussing su API porque obviamente la API no está funcionando correctamente.

Si emite un mensaje de error genérico, los desarrolladores harán lo posible por descubrir qué está pasando e inundar su foro, este sitio o su teléfono llamarán para preguntar por qué no funcionan sus servidores. (Hace poco tuve este problema con un proveedor que simplemente no entendía que un mensaje 404 no era una respuesta válida a un parámetro incorrecto y que la documentación debería reflejar los nombres de los parámetros reales utilizados ...)

Ahora, de la misma manera, esperaría que también diera un buen mensaje de error cuando falte un parámetro requerido. Por ejemplo, "Propiedad requerida: Falta el nombre" .

Esencialmente, desea ser lo más útil posible para que los consumidores de su API puedan ser tan autosuficientes como sea posible. Como puede ver, estoy totalmente en desacuerdo con un desglose "amable" contra "severo". Cuanto más "amable" seas, más probable es que los consumidores de tu API se encuentren con problemas en los que piensan que están haciendo lo correcto pero que están obteniendo comportamientos inesperados de tu API. No puede pensar en todas las formas posibles en que las personas van a arruinar, por lo que imponer una adherencia estricta con mensajes de error relevantes será de gran ayuda.

Imagina que tengo el siguiente esquema JSON:

{ "frequency": "YEARLY", "date": 23, "month": "MAY", }

El atributo de frecuencia acepta el valor "SEMANAL", "MENSUAL" y "ANUAL". La carga útil esperada para el valor de frecuencia "SEMANAL" es:

{ "frequency": "WEEKLY", "day": "MONDAY", }

Y la carga útil esperada para el valor de frecuencia "MENSUAL" es:

{ "frequency": "MONTHLY", "date": 23, }

Proporcione el esquema JSON anterior, normalmente necesitaré un POJO que contenga los campos de frecuencia, día, fecha y mes para la deserialización.

Si la carga útil recibida es:

{ "frequency": "MONTHLY", "day": "MONDAY", "date": 23, "year": 2018 }

Lanzaré un error en el atributo "día" porque nunca sabré la intención del remitente:

  1. frecuencia: "SEMANAL" y día: "LUNES" (se ingresó un valor de frecuencia incorrecto), o
  2. Frecuencia: "MENSUAL" y fecha: 23.

Para el atributo "año", realmente no tengo elección. Incluso si deseo lanzar un error para ese atributo, es posible que no pueda hacerlo. La biblioteca de serialización / deserialización JSON la ignora, ya que mi POJO no tiene dicho atributo. Y este es el comportamiento de GSON y tiene sentido dada la decisión de diseño.

Navegando por el árbol Json o el Árbol de tipos de destino mientras se deserializa

Cuando deserializa una cadena Json en un objeto del tipo deseado, puede navegar el árbol de la entrada o el árbol de tipo del tipo deseado. Gson utiliza el último enfoque para navegar por el tipo de objeto objetivo. Esto le permite tener un control estricto de la creación de instancias solo del tipo de objetos que está esperando (esencialmente validando la entrada contra el "esquema" esperado). Al hacer esto, también ignora los campos adicionales que la entrada Json tiene pero no se esperaban.

Como parte de Gson, escribimos un ObjectNavigator de propósito general que puede tomar cualquier objeto y navegar a través de sus campos llamando al visitante de su elección.

Extraído del documento de diseño GSON

Le sugeriré que ignore los parámetros adicionales. Reutilizar la API es un cambio de juego en el mundo de la integración. ¿Qué pasa si la misma API puede ser utilizada por otra integración pero con parámetros ligeramente adicionales?

Aplicación A esperando:

{ "name": "Jeff", "surname": "Atwood" }

Aplicación B esperando:

{ "name": "Jeff", "surname": "Atwood", "color": "red" }

La aplicación A de obtener la aplicación simple para ignorar el "color" hará el trabajo en lugar de tener 2 API diferentes para manejar eso.

Sólo ingoralos.

No le dé al usuario la oportunidad de aplicar ingeniería inversa a su API RESTful a través de sus mensajes de error.

Ofrezca a los desarrolladores la documentación más clara, clara y completa, y analice solo los parámetros que su API necesita y soporte.

Si realiza un diseño de API, puede seguir dos rutas: "stern" o "gracious".

  • Stern significa: si haces algo que no esperaba, me enfadaré contigo.
  • Gracioso significa: Si sé lo que quieres y puedes cumplirlo, lo haré.

REST permite un excelente diseño de API gracioso e intentaría seguir este camino el mayor tiempo posible y esperar lo mismo de mis clientes. Si mi API evoluciona, es posible que tenga que agregar parámetros adicionales en mis respuestas que solo sean relevantes para clientes específicos. Si mis clientes son amables conmigo, podrán manejar esto. Habiendo dicho eso, quiero añadir que hay un lugar para el diseño de API severas. Si está diseñando en un dominio sensible (por ejemplo, transacciones en efectivo) y no quiere dejar espacio para ningún malentendido entre el cliente y el servidor. Imagine la siguiente solicitud POST (válida para su / cuenta / {no} / transaction / API):

{ amount: "-100", currency : "USD" }

¿Qué harías con lo siguiente (solicitud de API no válida)?

{ amount: "100", currency : "USD", type : "withdrawal" }

Si simplemente ignora el atributo "tipo", depositará 100 USD en lugar de retirarlos. En tal dominio, seguiría un enfoque severo y no mostraría gracia alguna.

Sé amable si puedes, sé severo si debes.

Actualizar:

Estoy totalmente de acuerdo con la respuesta de @Chris Lively de que el usuario debe estar informado. No estoy de acuerdo en que siempre debería haber un caso de error, incluso si el mensaje no es ambiguo para el recurso al que se hace referencia. De lo contrario, dificultará la reutilización de las representaciones de recursos y requerirá el reenvasado de información semánticamente idéntica.