"Pensando en el diseño de servicios (2)" --- traducido de "Consideraciones para el diseño de servicios"

evitar accidentes

Las API pueden comportarse de manera impredecible debido a un uso inapropiado. Algunas decisiones de diseño sutiles a menudo crean una avalancha de desarrolladores posteriores.
Para ello se deben seguir las reglas que se muestran a continuación:

1. Se debe evitar el polimorfismo (polimorfismo), especialmente en la respuesta. Para evitar problemas inesperados cuando SDk se ejecuta dinámicamente, un punto final debe usar un solo tipo.
2. Se debe usar un solo tipo ( colección homogénea), y a menos que haya una muy buena razón para no devolver una colección heterogénea. Si cree que las colecciones heterogéneas son necesarias, discuta los requisitos con su revisor de API.
3. La paginación del lado del servidor debe ser compatible, incluso si sus recursos actualmente no requieren paginación. Esto evita que necesite interrumpir el servicio y luego cambiarlo cuando expanda el servicio.
4. Si el escenario del cliente realmente necesita admitir orderby y el servicio está seguro de que admitirá esta función de forma permanente, entonces puede admitir orderby
5. La idempotencia debe cumplirse cuando sea necesario: GET, PUT y DELETE en las solicitudes HTTP deben ser idempotentes.

Resiliencia a las modificaciones

Al diseñar sus servicios y API, considere una variedad de escenarios para agregar flexibilidad a las implementaciones de sus clientes. Se pueden tomar ciertas decisiones por adelantado para ayudar a que el desarrollo de software se itere rápidamente y evitar interrupciones del servicio para las actualizaciones.
Hay dos sugerencias:

1. Usar tipos de enumeración extensibles
2. Las solicitudes condicionales (como ETAG) deben implementarse lo antes posible para admitir la simultaneidad.

manipulación del comportamiento

La mayoría de las operaciones se ajustan a la interfaz REST estándar, y estas operaciones son una de una serie de operaciones como Crear, Leer, Actualizar, Eliminar o Listar (CRUDL).
Cuando un servicio puede permitir ID de recursos especificados por el usuario, la práctica recomendada es:

1. Restringe los ID de recursos especificados por el usuario para que sean alfanuméricos_-.
2. El uso de caracteres especiales que no están en los nombres de los recursos como acciones se diferencia en las rutas.
   Ejemplo de operación de recursos en Azure:
   https://.../<resource-collection>/<resource-id>:<action>?<input parameters>
   Por supuesto, también es posible usar otros modos.El factor central a considerar es garantizar que la información de operación en la ruta no colisione con la identificación del recurso.

Operaciones de larga duración

La operación larga es un patrón de diseño de API que se usa en escenarios en los que las operaciones tardan demasiado (más de lo que el cliente espera esperar para obtener un resultado). Azure permite este patrón de diseño en dos versiones, operaciones de ejecución prolongada basadas en recursos (RELO) y operaciones de ejecución prolongada con monitores de estado.
En ambos modos, después de una llamada a la API, se inicia el procesamiento de la operación y el cliente obtendrá el resultado de la operación en llamadas a la API posteriores. Los siguientes son ejemplos de estos patrones:

Operaciones de larga ejecución basadas en recursos (RELO)

En el modo RELO, el recurso del destino de la operación contiene un campo de estado para indicar si el recurso actual se ha preparado. Una vez que el cliente inicia la primera solicitud, puede obtener posteriormente el estado del recurso a través de una solicitud de obtención estándar para determinar si la operación se ha inicializado. El flujo de información correspondiente es el siguiente:

1. El cliente envía una solicitud de inicialización al recurso para inicializar la operación de ejecución prolongada. La operación de inicialización puede ser el método PUT, PATCH, POST o DELETE.
2. Una vez que el recurso verifica la solicitud, se inicializa el proceso de operación en el recurso. El recurso enviará el valor de retorno de 200-ok al cliente (o 201 para representar la operación de creación) y establecerá el valor de estado para indicar que la operación en el recurso ha comenzado.
3. El cliente enviará periódicamente solicitudes GET. para determinar si la operación del recurso ha finalizado.
4. El recurso restaura la información de estado sobre el recurso y utiliza valores de estado no terminales para representar el estado actual si las operaciones en el recurso aún están en curso.
5. Si el proceso de operación del recurso actual se ha completado, después de que el Cliente envíe la solicitud Get, el Recurso enviará una serie de valores indicativos como Correcto, Fallido o Cancelado para indicar el resultado actual.

Nota: este modo no es adecuado para escenarios en los que cada solicitud es importante para el Cliente

Operaciones de larga duración con monitor de estado

En el modo LRO, el estado y los resultados se completarán en el monitor de estado de recursos, y el monitor y el recurso de destino son dos partes separadas.

1. El cliente envía una solicitud de inicialización al recurso para inicializar la operación de ejecución prolongada. La operación de inicialización puede ser el método PUT, PATCH, POST o DELETE.
2. Una vez que el recurso verifica la solicitud, se inicializa el proceso de operación en el recurso. El recurso enviará el código de estado Http de 202-Aceptado al Cliente. Además, se incluyen direcciones URL para acceder a los monitores de estado para operaciones específicas. La Respuesta devuelta también incluirá el tiempo de espera mínimo en el campo Reintentar después.
3. Después de esperar el tiempo mínimo de espera, el Cliente enviará una solicitud GET al monitor de estado
4. El monitor de estado devolverá el valor de retorno correspondiente al cliente según el estado del recurso.
5. Si el estado de procesamiento del recurso es éxito, fracaso o cancelación, la información correspondiente será devuelta al Cliente.

Los LRO abrirán el oyente correspondiente para cada cliente, que es un modo uno a uno. LRO es un modelo de muchos a uno.

errores

Otra parte importante del diseño del servicio es el error devuelto por http. Los errores devueltos por los mensajes http son una parte fundamental de ser un desarrollador y una parte importante de la API que diseña para interactuar con otros. Si su servicio y el servicio del cliente juntos forman un sistema distribuido, los errores son inevitables. Un sistema de errores bien diseñado puede ayudarlo a evitar escenarios costosos de atención al cliente. Los clientes solo necesitan ver los errores para resolver sus propios problemas.
Debe diseñar posibles errores tanto como sea posible, puede consultar API GuideLines