Procedimientos recomendados para la implementación de la API web RESTful

En este artículo se describen los procedimientos recomendados para implementar, desplegar y operar una API web RESTful. Se centra en el control de solicitudes, el rendimiento, la confiabilidad, la publicación y la supervisión. Para obtener instrucciones sobre el modelado de recursos y el diseño de API, consulte Diseño de API web.

La guía de arquitectura se aplica a través de los lenguajes y marcos de implementación. Los ejemplos de C# muestran controladores de ASP.NET Core.

Procesamiento de solicitudes

Tenga en cuenta los puntos siguientes cuando implemente el código para administrar las solicitudes.

Conservar la semántica del método HTTP e implementar la idempoencia

Utilice GET para devolver datos de recursos y HEAD para devolver encabezados de respuesta sin un cuerpo. No use ninguno de los dos métodos para crear, actualizar ni eliminar recursos.

GET, HEAD, PUT y DELETE deben ser idempotentes, por lo que la repetición de una solicitud idéntica tiene el mismo efecto previsto que realizarla una vez. Por ejemplo, DELETE cambia el estado del recurso, pero repetirlo no elimina recursos adicionales. La primera solicitud DELETE podría devolver 204 (sin contenido), mientras que una solicitud posterior devuelve 404 (no encontrado).

POST y PATCH no son intrínsecamente idempotentes. Una operación PATCH que establece una propiedad en un valor puede ser idempotente, pero una que incrementa un contador no. Documente qué operaciones que cambian el estado pueden reintentarse de forma segura. Si su servicio admite reintentos para las operaciones que no son idempotentes de forma natural, implemente y documente cómo el servicio evita que se produzcan efectos duplicados. Para ver la semántica del método, consulte Métodos de solicitud HTTP.

Validar los datos de la solicitud, y controlar el acceso a los campos

Defina modelos de solicitud y respuesta que expongan solo los campos del contrato de API. Asigne estos modelos a los datos almacenados en lugar de enlazar cuerpos de solicitud directamente a entidades de base de datos o devolver todas las propiedades almacenadas. Impedir que los clientes cambien las propiedades protegidas mediante el envío de campos adicionales y omitir las propiedades que no estén autorizados a leer. Los objetos de transferencia de datos (DTO) son una manera de aplicar este límite. Para obtener más información, consulte Evitar la sobreasignación en ASP.NET Core.

Valide los campos obligatorios, los tipos, los intervalos y las reglas de negocio antes de guardar los cambios. Si admite la selección de campos, valide los campos solicitados comparándolos con una lista de permitidos y con los permisos de quien realiza la llamada antes de proyectar la respuesta. Aplique también límites documentados al filtrado y la ordenación. Para conocer las opciones de contrato correspondientes, consulte Implementar la paginación y el filtrado.

Limitar los efectos secundarios de las acciones POST que crean recursos

Cuando una solicitud POST crea un recurso, limite sus efectos a ese recurso y a los recursos relacionados directamente. Por ejemplo, la creación de un pedido también puede actualizar el inventario y generar información de facturación. No debe modificar la información no relacionada.

Evite implementar operaciones POST, PUT y DELETE que generen mucha conversación.

Evite diseñar la API en función de operaciones fragmentadas. Cada solicitud incluye el protocolo, la red y la sobrecarga de proceso. Por ejemplo, ejecutar 100 solicitudes más pequeñas en lugar de una solicitud por lotes mayor incurre en una sobrecarga adicional en el cliente, en la red y en el servidor de recursos. En el caso de las cargas de trabajo que necesitan operaciones masivas, considere la posibilidad de tener en cuenta las solicitudes por lotes con límite en lugar de muchas solicitudes individuales.

• Una solicitud GET para una colección puede recuperar varios recursos al mismo tiempo.
• Una solicitud POST puede contener los detalles de varios recursos nuevos y agregarlos a la misma colección.
• Una solicitud PUT puede reemplazar todo el conjunto de recursos de una colección.
• Una solicitud DELETE puede quitar toda una colección.

Defina los tamaños máximos de lote, los tamaños de carga, los tiempos de ejecución y la concurrencia. Especifique si un lote es atómico o puede tener éxito parcialmente, y devolver un resultado para cada operación. Autorice y valide cada operación del lote.

Si usa OData, puede usar ASP.NET Core OData para implementar solicitudes por lotes. Para obtener más información, consulte Información general de OData en ASP.NET Core.

Siga la especificación HTTP al enviar una respuesta.

Devuelve el código de estado HTTP, los encabezados y el formato de cuerpo adecuados para que los clientes puedan interpretar y controlar la respuesta.

Por ejemplo, una operación POST que crea un recurso de forma sincrónica debe devolver 201 (creado) e identificar el recurso en el encabezado de respuesta Location. Una operación que acepta el trabajo para el procesamiento posterior puede devolver 202 (aceptado), pero esa respuesta no indica que el trabajo haya tenido éxito. No incluya un cuerpo de respuesta con 204 (sin contenido) o 304 (no modificado). Para obtener más información, consulte Métodos de solicitud HTTP.

Apoye la negociación de contenido.

Un cuerpo de respuesta puede contener datos en diferentes formatos, como JSON o XML. Los clientes pueden usar el encabezado de solicitud Accept para especificar los tipos de medios admitidos. Por ejemplo, un cliente que solicita una imagen podría especificar image/jpeg, image/gif, image/png. Devuelve una representación admitida e identifica su tipo de medio en el encabezado de la respuesta Content-Type.

Si el cliente no especifica un encabezado Accept, use un formato predeterminado documentado. Los controladores de ASP.NET Core usan formateadores JSON de forma predeterminada. Defina lo que sucede cuando la API no puede generar una representación solicitada. Por ejemplo, configure la API para devolver 406 (no aceptable) en lugar de devolver de forma silenciosa un formato no admitido. Para obtener más información, consulte Dar formato a los datos de respuesta en ASP.NET Core API web.

En el caso de las solicitudes con un cuerpo, compruebe el valor de Content-Type de la solicitud y acepte solo los formatos que admite la operación. Devuelve 415 (tipo de medio no admitido) para un formato no admitido. Esta comprobación es independiente de la negociación de respuesta a través de Accept. En ASP.NET Core, configure formateadores de entrada y use [Consumes] cuando necesite restringir los formatos de solicitud de una operación. Para obtener más información, consulte Creación de API web con ASP.NET Core.

Implementar la estrategia de control de versiones de API seleccionada

Aplique la estrategia de control de versiones que eligió durante el diseño de forma coherente en la aplicación y la puerta de enlace. Enrutar las solicitudes al controlador y al esquema de respuesta de la versión seleccionada. Defina el comportamiento de identificadores de versión omitidos, con formato incorrecto y no admitidos en lugar de cambiar silenciosamente qué contrato recibe un llamador existente.

Conserve las interfaces de solicitud y respuesta de las versiones admitidas. Al introducir un cambio incompatible, proporcione una nueva versión y mantenga disponibles las versiones anteriores admitidas. Controle las solicitudes de los usuarios de versiones anteriores que omiten los campos opcionales recién agregados. Para más información, consulte Compatibilidad y control de versiones de API.

Mantenga los vínculos de recursos generados y las representaciones almacenadas en caché coherentes con la versión seleccionada. En el caso del control de versiones basado en encabezados, asegúrese de que las memorias caché distinguen las solicitudes de distintas versiones en lugar de confiar solo en el URI.

Resolver y autorizar el contexto del arrendatario

Para una API multiempresa, identifique la empresa para cada solicitud y compruebe que el autor de la llamada autenticado puede acceder a esa empresa. Trate los identificadores de tenant en rutas de acceso, nombres de host y encabezados solo como entradas de enrutamiento. Para más información, consulte Asignación de solicitudes a inquilinos en una solución multiinquilino.

Utilice el contexto de inquilino autorizado de forma coherente al consultar o actualizar datos y al entregar el trabajo a los procesadores en segundo plano. Si las cachés de la aplicación o de la puerta de enlace almacenan datos específicos del inquilino, incluya el identificador de inquilino en la clave de caché. Para obtener instrucciones específicas del gateway, consulte Características de API Management que admiten multiinquilinato.

Proporcione enlaces para admitir la navegación y el descubrimiento de recursos al estilo HATEOAS.

Hipertexto como motor de estado de aplicación (HATEOAS) usa vínculos para ayudar a los clientes a descubrir y navegar por los recursos. Por ejemplo, una respuesta que contiene los detalles del cliente puede incluir vínculos a los pedidos de ese cliente. Describa las operaciones que admite cada recurso vinculado, como GET, POST, PUT y DELETE, y proporcione los URI correspondientes. Para obtener más información, consulte Diseño de API.

En el ejemplo siguiente se usa una representación de vínculo definida por la aplicación. Documente sus convenciones en lugar de asumir que los clientes pueden interpretar campos de vínculo personalizados. Una solicitud GET para un cliente devuelve vínculos a los pedidos de ese cliente:

GET https://api.contoso.com/customers/2 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
...
Content-Type: application/json; charset=utf-8
...
Content-Length: ...
{"customerId": 2,"customerName": "Bert","links": [
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "PUT",
     "types": ["application/x-www-form-urlencoded"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "DELETE",
     "types": []},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "POST",
     "types": ["application/x-www-form-urlencoded"]}
]}

El registro siguiente Customer representa los datos del cliente. Su propiedad Links contiene los vínculos HATEOAS.

public sealed record Customer(
    int CustomerId,
    string CustomerName,
    IReadOnlyList<Link> Links);

public sealed record Link(
    string Rel,
    string Href,
    string Action,
    IReadOnlyList<string> Types);

La operación GET recupera los datos del cliente del almacenamiento, crea un Customer registro con sus vínculos y devuelve una respuesta JSON. Todos los enlaces incluyen los siguientes campos:

• Relación (Rel) entre el recurso devuelto y el recurso vinculado. En este ejemplo, self hace referencia al cliente y orders hace referencia a la colección de pedidos del cliente.
• Hipervínculo (Href) para el objeto descrito por el vínculo, en forma de URI.
• Tipo de solicitud HTTP (Action) que se puede enviar al URI.
• El formato de los datos (Types) que deben facilitarse en la solicitud HTTP o que se pueden devolver en la respuesta, según el tipo de la solicitud.

Los vínculos de HATEOAS que se muestran en la respuesta HTTP de ejemplo indican que una aplicación cliente puede realizar las siguientes operaciones:

• Solicitud HTTP GET para https://api.contoso.com/customers/2 recuperar los detalles del cliente como XML o JSON.
• Solicitud HTTP PUT para https://api.contoso.com/customers/2 modificar los detalles del cliente. El cuerpo de la solicitud usa este formato: application/x-www-form-urlencoded.
• Solicitud HTTP DELETE para https://api.contoso.com/customers/2 eliminar el registro del cliente. Esta operación no requiere ningún cuerpo de solicitud y no devuelve ningún cuerpo de respuesta.
• Una solicitud HTTP GET a https://api.contoso.com/customers/2/orders para recuperar los pedidos del cliente como XML o JSON.
• Solicitud HTTP POST a https://api.contoso.com/customers/2/orders para crear un pedido para el cliente. El cuerpo de la solicitud usa este formato: application/x-www-form-urlencoded.

Control de excepciones

Si una operación produce una excepción que no se controla, tenga en cuenta las instrucciones siguientes.

Capture las excepciones y devuelva una respuesta significativa a los clientes.

Controle las excepciones de forma coherente y devuelva una respuesta de error significativa que sea segura para compartir con los clientes. No devuelva objetos de excepción, seguimientos de pila ni detalles de implementación internos en las respuestas de producción. Devuelve un código de estado HTTP que refleja el error en lugar de devolver el código de estado 500 para cada situación. Por ejemplo, si una solicitud de usuario provoca una actualización de base de datos que infringe una restricción (como intentar eliminar un cliente que tiene pedidos pendientes), devuelva 409 (Conflicto) y una explicación segura. Devuelve 400 (solicitud incorrecta) para errores de validación de solicitudes o entradas con formato incorrecto, no para errores inesperados del servidor. Para obtener definiciones de estado HTTP, consulte Códigos de estado. Para obtener instrucciones de implementación, consulte Controlar errores en ASP.NET Core.

El controlador siguiente asigna los resultados esperados del dominio a las respuestas HTTP. Su operación de repositorio comprueba la autorización y los pedidos pendientes como parte de la operación de eliminación. Los errores inesperados se propagan al control centralizado de excepciones en lugar de capturarse silenciosamente en cada acción.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("customers")]
public sealed class CustomersController(ICustomerRepository repository) : ControllerBase
{
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> DeleteCustomer(int id, CancellationToken cancellationToken)
    {
        var outcome = await repository.DeleteAuthorizedAsync(id, User, cancellationToken);

        return outcome switch
        {
            DeleteOutcome.Deleted => NoContent(),
            DeleteOutcome.NotFound => NotFound(),
            DeleteOutcome.HasOutstandingOrders => Conflict(new ProblemDetails
            {
                Status = StatusCodes.Status409Conflict,
                Title = "The customer has outstanding orders."
            }),
            _ => throw new InvalidOperationException("Unknown deletion outcome.")
        };
    }
}

public enum DeleteOutcome
{
    Deleted,
    NotFound,
    HasOutstandingOrders
}

La capa de hospedaje puede rechazar las solicitudes antes de que lleguen a la API. Por ejemplo, los errores de autenticación pueden dar lugar a respuestas 401 (no autorizadas). Después de la autenticación, compruebe que quien realiza la llamada está autorizado para acceder al recurso solicitado. Devuelve 403 (Prohibido) cuando falle la autorización.

Controle las excepciones de una forma coherente y registre la información sobre los errores.

Para controlar las excepciones de forma coherente, considere la posibilidad de implementar una estrategia global de control de errores en toda la API web. Registre información de diagnóstico en el servidor, pero excluya secretos, tokens de acceso y datos personales confidenciales. Redacte valores confidenciales antes de escribir entradas de registro y limite el acceso de registro a los usuarios autorizados. Para obtener más información, consulte Estrategias de arquitectura para la supervisión y la detección de amenazas.

En ASP.NET Core, usa el middleware de control de excepciones y las respuestas Problem Details para un contrato de error coherente. Configure las respuestas de producción para omitir los detalles de diagnóstico e incluya un identificador de correlación que los equipos de soporte puedan usar para localizar los registros correspondientes. Para más información, consulte Control de errores en ASP.NET Core.

Distinga entre los errores del lado cliente y del lado servidor.

Utilice códigos de estado HTTP 4xx para errores de cliente y códigos de estado HTTP 5xx para errores de servidor. Conserve esta distinción en las respuestas de error.

Optimización del acceso a los datos en el lado cliente

Las solicitudes frecuentes y las respuestas grandes pueden hacer que la red sea un cuello de botella. Reduzca las transferencias innecesarias al implementar la recuperación y las actualizaciones de recursos.

Admita el almacenamiento en caché del lado cliente.

Utilice el Cache-Control encabezado de respuesta para especificar si los clientes y los servidores intermedios pueden almacenar una respuesta y cuánto tiempo permanece vigente.

En el ejemplo siguiente se muestra una solicitud HTTP GET y la respuesta correspondiente que incluye un encabezado Cache-Control:

GET https://api.contoso.com/orders/2 HTTP/1.1

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

En este ejemplo, la respuesta permanece actualizada durante 600 segundos. La private directiva permite el almacenamiento en una caché privada, como una caché del explorador, pero prohíbe el almacenamiento en una caché compartida. Usa public solo para las respuestas que son seguras para compartir entre usuarios que llaman. Se usa no-store para las respuestas confidenciales que no se deben almacenar.

En un controlador ASP.NET Core, establezca los encabezados de caché antes de devolver la respuesta:

Response.GetTypedHeaders().CacheControl = new Microsoft.Net.Http.Headers.CacheControlHeaderValue
{
    Private = true,
    MaxAge = TimeSpan.FromMinutes(10)
};

La API controla la directiva de caché y los validadores en sus respuestas. Los clientes y los servidores intermedios usan esa información para administrar sus memorias caché. Establezca estos encabezados de forma coherente para que los clientes puedan reutilizar las respuestas sin transferencias de datos innecesarias.

Para determinar max-age, considere cuánta obsolescencia puede tolerar la carga de trabajo. Un recurso puede cambiar mientras una respuesta almacenada en caché sigue siendo nueva. Cuando expira la vigencia, una memoria caché puede volver a validar la respuesta en lugar de descartarla y volver a descargar toda la representación. No use un tiempo de vigencia prolongado para los datos que requieran visibilidad inmediata de los cambios.

Proporcione ETags para optimizar el procesamiento de las consultas.

Una etiqueta de entidad (ETag) es un validador opaco para una representación seleccionada de un recurso. Los clientes pueden conservarla con una respuesta almacenada en caché y enviarla en If-None-Match para comprobar si la representación ha cambiado. Una solicitud GET o HEAD coincidente devuelve 304 (no modificado) sin un cuerpo de respuesta.

Genere un validador que siga siendo coherente entre las instancias de la aplicación y que cambie cuando cambie la representación.

El controlador siguiente aplica hash a los bytes JSON exactos que devuelve y reutiliza las opciones JSON configuradas de la aplicación. FileContentResult aplica el control de respuesta condicional de ASP.NET Core sin contenedores de resultados personalizados. El repositorio devuelve solo un pedido que el solicitante está autorizado a leer. Configure la autenticación y la autorización en la aplicación host.

using System.Security.Cryptography;
using System.Text.Json;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using Microsoft.Net.Http.Headers;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrdersController(IOrderRepository repository,IOptions<JsonOptions> jsonOptions) : ControllerBase
{
    [HttpGet("{id:int}")]
    [HttpHead("{id:int}")]
    public async Task<IActionResult> GetOrder(int id, CancellationToken cancellationToken)
    {
        var order = await repository.FindAuthorizedAsync(id, User, cancellationToken);
        if (order is null)
        {
            return NotFound();
        }

        var payload = JsonSerializer.SerializeToUtf8Bytes(order, jsonOptions.Value.JsonSerializerOptions);
        var etag = new EntityTagHeaderValue($"\"{Convert.ToHexString(SHA256.HashData(payload))}\"");

        Response.GetTypedHeaders().CacheControl = new CacheControlHeaderValue
        {
            Private = true,
            MaxAge = TimeSpan.FromMinutes(10)
        };

        return new FileContentResult(payload, "application/json")
        {
            EntityTag = etag
        };
    }
}

En este ejemplo se almacena en búfer la representación y se lee el orden incluso para una solicitud condicional. Úselo solo con respuestas acotadas y no sensibles. Para recursos grandes, considere la posibilidad de usar un token de versión almacenado que cambie cada vez que cambie la representación seleccionada, de modo que pueda validar una solicitud sin generar la carga completa. Si la negociación de contenido, la compresión o las transformaciones de pasarela cambian la representación, asegúrese de que los validadores y la variación de caché sigan siendo correctos para esa representación.

Una respuesta incluye la directiva ETag y la política de caché. En los ejemplos siguientes se muestran los primeros 16 caracteres hexadecimales (64 bits) del hash SHA-256 del cuerpo JSON mostrado, seguido de ... para mayor brevedad. Los encabezados reales contienen el hash completo sin los puntos suspensivos.

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
ETag: "3097D1FD51082205..."
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

Admita solicitudes GET condicionales para que quienes realizan las llamadas puedan volver a validar las respuestas almacenadas en caché sin descargar una representación sin cambios. Implemente el siguiente comportamiento de solicitud y respuesta:

1. Acepte solicitudes GET condicionales que proporcionen una ETag en el encabezado If-None-Match, como:

   GET https://api.contoso.com/orders/2 HTTP/1.1
   If-None-Match: "3097D1FD51082205..."
   

2. Compare la ETag actual del recurso solicitado (pedido 2 en este ejemplo) con la condición If-None-Match.

   • Si la condición coincide, devuelva 304 (No modificado) sin un cuerpo de respuesta.

   • Si la condición no coincide, devuelva 200 (OK) con la representación actual.

   • Si el recurso solicitado ya no existe, devuelva 404 (no encontrado).

Use la compatibilidad con el framework para las solicitudes condicionales siempre que sea posible. Si implementa comparaciones usted mismo, controle todas las etiquetas de entidad proporcionadas, condiciones de caracteres comodín y reglas de comparación débiles frente a reglas de comparación sólidas en lugar de comparar solo la primera etiqueta. Incluya los encabezados ETag y caché adecuados en las respuestas 304 (sin modificar) y realice la autorización antes de devolver metadatos de recursos.

Uso de ETags para admitir la concurrencia optimista

Para evitar actualizaciones perdidas, evalúe If-Match las condiciones previas en las solicitudes de cambio de estado comparándolas con la ETag actual del recurso. Esto permite que la API rechace un cambio en función de una representación que ya haya modificado otra operación. Implemente el siguiente comportamiento:

1. Acepte solicitudes de actualización que identifiquen la versión esperada en el encabezado If-Match. La siguiente solicitud PUT actualiza el pedido 2. Usa la ETag de la respuesta GET anterior, abreviada de la misma manera. La etiqueta identifica la representación existente, no el nuevo cuerpo de la solicitud:

   PUT https://api.contoso.com/orders/2 HTTP/1.1
   If-Match: "3097D1FD51082205..."
   Content-Type: application/x-www-form-urlencoded
   Content-Length: 37
   
   productId=3&quantity=5&orderValue=250
   

2. Compare la ETag actual del recurso solicitado (orden 2 en este ejemplo) con la condición If-Match.

   • Si la condición previa coincide, realice la actualización de forma atómica y devuelva la respuesta de éxito documentada, como 204 (sin contenido). Un Location encabezado no es necesario simplemente porque se actualizó un recurso existente. Solo devuelve una ETag en una respuesta PUT correcta cuando satisface los requisitos de validador de HTTP para la representación almacenada.

   • Si la condición no se cumple, devuelva 412 (Condición previa fallida). En este ejemplo no se devuelve ningún cuerpo de respuesta.

   • Si el recurso que se va a actualizar ya no existe, devuelva 404 (no encontrado).

3. Documente las respuestas correctas y en conflicto para que quienes llamen puedan determinar si una actualización se realizó correctamente o si necesitan recuperar la representación actual antes de enviar otro cambio.

En el caso de las operaciones que deben evitar actualizaciones perdidas, requiera una If-Match condición previa y devuelva 428 (condición previa requerida) cuando falte. Usa una comparación estricta para If-Match.

Al comprobar una versión en la memoria de la aplicación y, a continuación, guardar incondicionalmente se crea una condición de carrera. Aplique la comparación de versiones y la escritura atómicamente en el almacén de datos. Por ejemplo, use un token de simultaneidad de base de datos para que la actualización se realice correctamente solo si la versión almacenada sigue coincidiendo con la versión usada para evaluar la solicitud.

En Entity Framework (EF) Core, configure un token de simultaneidad y controle DbUpdateConcurrencyException el conflicto en lugar de sobrescribir un cambio simultáneo. En el código de acceso a datos de la API, no reemplace automáticamente la versión esperada y vuelva a intentar una actualización de base de datos en conflicto a menos que la semántica de la operación lo permita. Para obtener más información, consulte Gestión de conflictos de concurrencia.

Administración de respuestas y solicitudes de gran tamaño

Los cuerpos de solicitud y respuesta grandes consumen memoria de API, ancho de banda y capacidad de conexión. Implemente streaming y límites de recursos para que las transferencias grandes no agoten el servicio. Tenga en cuenta los siguientes puntos al manejar cantidades significativas de datos:

Optimice las solicitudes y respuestas que impliquen objetos grandes.

Para objetos grandes, como imágenes u otros datos binarios, admita cargas y descargas de streaming.

Use las API de streaming asincrónicas y permita que el servidor seleccione el marco de transferencia para la versión HTTP negociada. No agregue Transfer-Encoding: chunked manualmente a cada parte de una respuesta. El streaming no se limita a la codificación por fragmentos de HTTP/1.1. Evite almacenar en búfer toda una solicitud o respuesta sin límites en la memoria de la aplicación.

Establezca los límites del cuerpo de la solicitud, los límites de carga, los tiempos de espera y las directivas de cancelación en las capas de aplicación y hospedaje. Rechace una solicitud sobredimensionada con 413 (contenido demasiado grande) antes de iniciar la respuesta.

La compresión HTTP puede reducir el tamaño de la transferencia, a costa del procesamiento adicional en el servidor y el cliente. Por ejemplo, un cliente puede enviar Accept-Encoding: gzip. Si el servidor devuelve contenido comprimido por gzip, identifique la codificación mediante Content-Encoding: gzip.

Configure la compresión a través de la plataforma de hospedaje o middleware y mida sus compensaciones de CPU y ancho de banda en los lados del cliente y del servidor.

• Evite volver a comprimir los formatos que ya están comprimidos.
• Antes de habilitar la compresión para las respuestas HTTPS generadas dinámicamente, evalúe los riesgos de compresión, como BREACH, y aplique las mitigaciones adecuadas. Incluso si deshabilita la compresión HTTPS en el middleware, es posible que el servidor de hospedaje se configure para aplicar la compresión.
• Asegúrese de que la variación de caché y las etiquetas ETag siguen siendo correctas cuando cambia la codificación de contenido.

Para obtener instrucciones de implementación de compresión y consideraciones de seguridad, consulte Compresión de respuesta en ASP.NET Core.

Admite descargas parciales de recursos grandes

Si la API admite descargas parciales de recursos grandes, anuncie esa funcionalidad con Accept-Ranges. Controle las solicitudes HEAD devolviendo los metadatos del recurso, incluido su total Content-Length, sin un cuerpo de respuesta. Para las solicitudes GET que especifican un intervalo de bytes admitido, devuelve 206 (contenido parcial), un Content-Length para la parte devuelta y un Content-Range que identifica esa parte del recurso. Este contrato de respuesta permite a los llamadores recuperar partes de un recurso sin necesidad de que la API devuelva todo el objeto.

Las respuestas parciales y las solicitudes HTTP HEAD se describen con más detalle en Diseño de API.

Gestionar 100-Continue en subidas grandes

Para una carga HTTP/1.1 grande, un cliente puede enviar encabezados de solicitud con Expect: 100-continue y esperar antes de transmitir el cuerpo. El servidor puede enviar una respuesta provisional 100 (Continuar) o rechazar la solicitud sin recibir el cuerpo completo. Este intercambio forma parte de una solicitud, no una solicitud vacía preliminar seguida de una segunda solicitud completa.

Configure y pruebe cómo la pila de alojamiento y la puerta de enlace controlan las solicitudes con y sin Expect: 100-continue. Compruebe el comportamiento de la API cuando acepta o rechaza una carga y mida los efectos en el uso de recursos del servidor y la latencia de las solicitudes.

Admite la paginación para solicitudes que podrían devolver un gran número de objetos

La recuperación de una colección completa de gran tamaño puede aumentar el procesamiento del servidor, el tráfico de red y la latencia.

Valide las entradas de paginación en el servidor y aplique un tamaño máximo de página. El controlador siguiente muestra la validación de solicitudes. El valor predeterminado es 10 resultados y rechaza los límites fuera de 1 a 100 o desplazamientos fuera de 0 a 10 000. Estos límites son ilustrativos. Elija los límites en función de la carga de trabajo y las pruebas de carga. Cuando se usa [ApiController], los errores de validación producen una respuesta 400. Para más información, consulte Creación de API web con ASP.NET Core.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrderCollectionsController(IOrderRepository repository) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<IReadOnlyList<Order>>> GetOrders(
        [FromQuery, Range(1, 100)] int limit = 10,
        [FromQuery, Range(0, 10000)] int offset = 0,
        CancellationToken cancellationToken = default)
    {
        var orders = await repository.ListAuthorizedAsync(limit, offset, User, cancellationToken);
        return Ok(orders);
    }
}

Un cliente puede solicitar 30 pedidos a partir del desplazamiento 50 mediante https://api.contoso.com/orders?limit=30&offset=50.

Más allá de la validación de solicitudes que se muestra en el ejemplo anterior, incluya un vínculo de página siguiente o un token de continuación en el contrato de respuesta. Por ejemplo, devuelve los pedidos con una propiedad nextLink establecida en https://api.contoso.com/orders?limit=30&offset=80 cuando hay otra página disponible. Conserve los filtros, el criterio de ordenación y la versión de api en el vínculo. Omita nextLink o establézcalo en null en la última página. Para obtener un ejemplo de un contrato nextLink, consulte paginación de Microsoft Graph.

Aplicar filtrado y paginación en el almacén de datos, no después de cargar toda la colección. Utilice un criterio de ordenación determinista. Para colecciones grandes o que cambian con frecuencia, evalúe la paginación basada en cursores para evitar desplazamientos costosos y límites de página inestables.

Mantenimiento de la capacidad de respuesta, la escalabilidad y la disponibilidad

Defina los objetivos de latencia, rendimiento y disponibilidad para las operaciones críticas de la API. Diseñe y pruebe para el tráfico esperado, los picos y los fallos de dependencias. El escalado horizontal y la gestión sin estado respaldan esos objetivos. Tenga en cuenta los siguientes requisitos de implementación.

Ofrezca compatibilidad asincrónica para las solicitudes de ejecución prolongada.

Para el trabajo que dure más que una solicitud HTTP normal, valide y autorice la solicitud, registre de forma duradera el trabajo y devuelva 202 (Aceptado). No confíe en que una tarea en proceso no supervisada finalice después de una respuesta: los reinicios de la aplicación, la reducción de escala y el despliegue pueden interrumpirla. Utilice una cola duradera y un proceso trabajador duradero o un flujo de trabajo duradero cuando el trabajo debe continuar ejecutándose a pesar de esos eventos. Para obtener la guía completa de implementación y semántica HTTP, consulte Patrón de Request-Reply asincrónico.

Proporcione una manera de que los clientes que realizan la llamada recuperen el estado y el resultado de la operación. La API también puede notificar a quienes realizan la llamada cuando se completa el procesamiento.

Puede proporcionar un recurso de estado que sondean los clientes:

1. El cliente envía la solicitud. Valide su entrada de datos y permisos antes de aceptar la tarea.
2. Conserve un identificador de operación y el estado en un almacenamiento duradero, como Azure Table Storage, y ponga en cola el trabajo para un procesador independiente, por ejemplo, mediante Azure Service Bus. Coordinar la persistencia y la puesta en cola para que un error entre estas dos acciones no produzca la pérdida de trabajo aceptado.
3. Devuelve 202 con un Location encabezado que identifica el punto de conexión de estado y un Retry-After encabezado que controla la frecuencia de sondeo. Acepte la solicitud solo después de que el trabajo se haya guardado de forma permanente.
4. Un trabajador procesa la operación y actualiza su estado duradero. Hacer que el procesamiento sea idempotente porque un trabajador puede recibir el mismo trabajo más de una vez. Aplicar reintentos limitados a errores transitorios.
5. El cliente sondea el endpoint de estado. Se aplica la autorización de nivel de recurso en los puntos de conexión de estado y resultado. Un identificador imposible de adivinar no es autorización.
6. Devuelve una representación de estado documentada mientras el trabajo está en curso. Al finalizar, proporcione el resultado o un redireccionamiento 303 (See Other) a un recurso de resultado. Notificar fallos a través de un contrato de error coherente y seguro.
7. Defina la retención y la limpieza de los registros de operación y los resultados. Expiración de la operación de documento, envíos duplicados y cualquier comportamiento de cancelación admitido.

En el caso de los clientes conectados, considere la posibilidad de usar ASP.NET Core SignalR para las notificaciones de finalización. Mantenga el recurso de estado duradero disponible para que los clientes puedan recuperarse después de una desconexión o notificación perdida. Para obtener más información, consulte Descripción general de ASP.NET Core SignalR.

Asegúrese de que ninguna de las solicitudes tenga estado.

No requiera una solicitud posterior para llegar a la misma instancia de aplicación que una solicitud anterior. Mantenga el estado de los recursos y el flujo de trabajo en los almacenes compartidos adecuados, no solo en la memoria del proceso. Las solicitudes pueden depender del estado de recurso duradero sin crear afinidad de instancia de servidor. El control de solicitudes sin estado admite el escalado horizontal.

Entienda sus dependencias descendentes

Establezca un tiempo de espera para cada llamada a un servicio descendente. Mantenga el tiempo total de llamadas, reintentos y retrasos dentro de la fecha límite de la solicitud de API y propague la cancelación de solicitudes a las operaciones posteriores.

Reintente solo los fallos transitorios y las operaciones que sean seguras de repetir. Use reintentos enlazados con retroceso y vibración. Limite los reintentos agregados por dependencia, así como los intentos por solicitud. Para obtener más información, consulte Administración de errores transitorios.

Utilice un patrón circuit breaker cuando los errores de dependencia repetidos podrían agotar la capacidad de la API.

Realice un seguimiento de los clientes e implemente la limitación para reducir las posibilidades de ataques de denegación de servicio.

Aplique límites de frecuencia de solicitud, simultaneidad, carga útil y tiempo de ejecución. Divida los límites de partición por solicitante autenticado o tenant siempre que sea posible. Devuelve 429 (demasiadas solicitudes) cuando un cliente supera una tasa configurada y 503 (servicio no disponible) para la falta de disponibilidad temporal del servicio. Incluya Retry-After cuando corresponda. Si la API vuelve a intentar llamadas a dependencias posteriores, limita esos reintentos para que no amplifiquen la sobrecarga.

Los límites de puerta de enlace y aplicación sirven para diferentes propósitos. Los límites de gateway pueden proteger la capacidad compartida. Los límites de la aplicación pueden reflejar el costo de operación y la capacidad aguas abajo. Tampoco reemplaza la protección contra DDoS de capa de red o un firewall de aplicaciones web. Para obtener más información, consulte Patrón de limitación.

Administre con cuidado las conexiones HTTP persistentes.

Para las conexiones entrantes, configure los tiempos de espera de keep-alive de la puerta de enlace y el servidor, los tiempos de espera de solicitud y los límites de conexión simultáneos para la ruta de acceso de red y la carga de trabajo. No obligue de forma rutinaria a que las conexiones se cierren después de cada respuesta. Para obtener información sobre la configuración del servidor de ASP.NET Core, vea Configurar opciones para el servidor web Kestrel.

Si la PROPIA API llama a servicios HTTP aguas abajo, reutilice esas conexiones salientes. En una implementación de api de .NET, use instancias de larga duración HttpClient con un adecuado PooledConnectionLifetimeo use los clientes creados por IHttpClientFactory. Elimine los mensajes y secuencias de respuesta salientes cuando ya no sean necesarios. Esta configuración se aplica a las llamadas descendentes de la API, no a las conexiones de cliente entrantes. Para más información y advertencias sobre el control de cookies, consulte Directrices para usar HttpClient.

Publicación y administración de una API web

Implemente la API en un entorno de hospedaje que cumpla sus requisitos operativos. Tenga en cuenta las estrategias siguientes:

• Utilice HTTPS. Autentique las solicitudes a los puntos de conexión protegidos y aplique la autorización para cada recurso y operación.
• Escale el entorno de hospedaje para cumplir los compromisos en tiempo de respuesta a medida que cambia la demanda.
• Contabilice las solicitudes si el modelo de facturación de la API lo requiere.
• Regular el tráfico y aplicar cuotas por cliente cuando sea necesario.
• Registre los eventos de auditoría que exigen el cumplimiento normativo y la respuesta ante incidentes, pero no registre credenciales, tokens o cuerpos de solicitud y respuesta confidenciales.
• Supervise el estado del host y defina las acciones de recuperación, como reiniciar un host no operativo.

Considere la posibilidad de usar una fachada independiente que gestione los aspectos comunes de gestión y reenvíe las solicitudes validadas a la API. Una fachada puede proporcionar las siguientes funcionalidades:

• Actuar como un punto de integración para varias API web.
• Transformar los mensajes y traducir protocolos de comunicaciones de los clientes creados mediante tecnologías distintas.
• Almacenar en caché solicitudes y respuestas para reducir la carga en el servidor que hospeda la API web.

Mantenga los contratos de API y la configuración de puerta de enlace bajo el control de versiones, valide los cambios en las canalizaciones de implementación y defina los procedimientos de reversión. Alinee el alojamiento, la identidad, las redes y la gobernanza con el enfoque de landing zone de la organización. Para más información, consulte ¿Qué es una zona de aterrizaje de Azure?.

Prueba de una API web

Utiliza pruebas unitarias para validar la lógica de la API y pruebas de integración para comprobar su comportamiento HTTP.

Incluya las siguientes comprobaciones:

• Pruebe todas las rutas para comprobar que invocan las operaciones correctas. Tenga especialmente en cuenta que el código de estado HTTP 405 (método no permitido) se devuelve inesperadamente. Este código de estado puede indicar un error de coincidencia entre una ruta y los métodos HTTP (GET, POST, PUT, DELETE) que se pueden dirigir a esa ruta.

  Envíe solicitudes que usan métodos que no son compatibles con cada ruta y compruebe la respuesta 405 documentada (método no permitido) y el encabezado Allow.

• Compruebe que todas las rutas estén protegidas correctamente y que estén sujetas a las comprobaciones de autenticación y autorización apropiadas.

  Nota

  Es probable que algunos aspectos de la seguridad, como la autenticación de usuario, sean responsabilidad del entorno de host en lugar de la API web, pero todavía necesita incluir pruebas de seguridad como parte del proceso de implementación.

• Pruebe el control de excepciones que realiza cada operación y compruebe que se pasa una respuesta HTTP adecuada y significativa de vuelta a la aplicación cliente.

• Compruebe que los mensajes de solicitud y respuesta están formados correctamente. Por ejemplo, para una solicitud POST que crea un recurso, compruebe la deserialización, el análisis, la creación del recurso y el encabezado Location de la respuesta.

• Pruebe los tipos de medios de solicitud admitidos y no admitidos independientemente de la negociación de contenido de respuesta. Compruebe las respuestas 415 (tipo de medio no admitido) para los formatos de solicitud no admitidos y los errores de validación documentados para cuerpos con formato incorrecto.

• Pruebe cada versión de API compatible, incluido su enrutamiento, validación de solicitudes y esquema de respuesta. Pruebe los identificadores de versión omitidos, con formato incorrecto y no admitidos, y compruebe que las respuestas almacenadas en caché no traspasen los límites entre versiones.

• Compruebe todos los vínculos y los URI de los mensajes de respuesta. Por ejemplo, un mensaje HTTP POST debe devolver el URI del recurso recién creado. Todos los vínculos HATEOAS deben ser válidos.

• Asegúrese de que cada operación devuelve los códigos de estado correctos para diferentes combinaciones de entradas. Por ejemplo:

  • Si una consulta se realiza correctamente, debe devolver el código de estado 200 (Correcto).
  • Si no se encuentra un recurso, la operación debe devolver el código de estado HTTP 404 (no encontrado).
  • Si el cliente envía una solicitud que elimina correctamente un recurso, el código de estado debe ser 204 (sin contenido).
  • Si el cliente envía una solicitud que crea un nuevo recurso, el código de estado debe ser 201 (creado).

  Investigue las respuestas inesperadas de 5xx de la aplicación o la capa de hospedaje.

• Pruebe las distintas combinaciones de encabezados de solicitud que una aplicación cliente puede especificar y asegúrese de que la API web devuelve la información esperada en los mensajes de respuesta.

• Pruebe las cadenas de consultas. Si una operación puede tomar parámetros opcionales (como solicitudes de paginación), pruebe las diferentes combinaciones y el orden de los parámetros.

• Compruebe que las operaciones asincrónicas se completan correctamente. Para las respuestas de streaming, compruebe que la API no almacena en búfer toda la carga y que controla las desconexiones de cliente y la cancelación correctamente. Si la API proporciona recursos de estado para las operaciones de ejecución prolongada, compruebe que notifican el progreso de la operación y los resultados correctamente.

Pruebe los casos de error y límite que afectan a la corrección:

• Valide entradas de paginación y por lotes mínimas, máximas, negativas, con formato incorrecto y excesivas.
• Siga los vínculos de paginación hasta la última página. Compruebe que los vínculos conservan las opciones de consulta y que se devuelve la señal de finalización documentada.
• Compruebe que los campos de entrada adicionales no pueden cambiar las propiedades protegidas y que la selección de campos no puede exponer datos no autorizados.
• Pruebe ETags coincidentes, no coincidentes, débiles, múltiples y comodín, y compruebe que las respuestas 304 no contienen ningún cuerpo.
• Pruebe actualizaciones simultáneas y confirme que el almacén de datos rechaza escrituras obsoletas de forma atómica.
• Compruebe que los llamantes no pueden leer los recursos, los registros de estado o las respuestas almacenadas en caché de otro llamante.
• En el caso de las API multicliente, pruebe los identificadores de inquilino falsificados o no coincidentes. Cuando el almacenamiento en caché está habilitado, compruebe si hay solicitudes para el mismo URI de recurso de diferentes arrendatarios.
• Simulación de tiempos de espera, cancelación de cliente, errores de dependencia, reinicios del trabajador y entrega duplicada del trabajo en segundo plano.
• Compruebe el tiempo de espera de servicios posteriores y los presupuestos de reintento, la cancelación y la recuperación del interruptor de circuito.
• Compruebe las respuestas 429 (demasiadas solicitudes) y 503 (servicio no disponible), el comportamiento de reintento y el costo de rechazar las solicitudes en situación de sobrecarga.

Ejecute pruebas de carga en una infraestructura similar a producción y con combinaciones de operaciones realistas. Defina los criterios de aprobación y fallo para el rendimiento, los percentiles de latencia, las tasas de error y la saturación de recursos. Use Azure Load Testing e integre las comprobaciones de regresión en la canalización de implementación.

Uso de la administración de API

Considere la posibilidad de usar Azure API Management cuando necesite una puerta de enlace administrada con la aplicación de directivas. Agrega costo, otro salto de red y una dependencia en la ruta de acceso de la solicitud. Elija un nivel de servicio y una topología en función de la capacidad, las redes, la disponibilidad y los requisitos regionales; las características difieren según el nivel. El nivel Desarrollador no está pensado para cargas de trabajo de producción. Siga la guía del servicio Well-Architected para API Management.

Para publicar y administrar una API web, siga estos pasos:

1. Implemente la API web en una plataforma de hospedaje como Azure App Service, Azure Container Apps, Azure Kubernetes Service (AKS) o Azure Virtual Machines.

2. Configure API Management para dirigir las solicitudes desde la dirección URL de su puerta de enlace a la API de back-end. Una instancia de API Management puede enrutar solicitudes a varias API. Varias instancias también pueden exponer la misma API de back-end cuando las aplicaciones necesitan límites de acceso diferentes.

   Nota

   Los vínculos HATEOAS en las respuestas deben hacer referencia a la dirección URL de la puerta de enlace de API Management, no a la dirección URL del servidor back-end.

3. Importe una definición de OpenAPI controlada por versiones y valide que las operaciones, parámetros, requisitos de seguridad y esquemas de respuesta importados coincidan con la implementación. Compruebe las versiones admitidas de OpenAPI y las limitaciones de importación. Para obtener más información, consulte Importación de una especificación de OpenAPI.

4. Configure la autenticación y la autorización para las comunicaciones de cliente a puerta de enlace y de puerta de enlace a back-end. Valide los tokens de acceso de OAuth 2.0 y aplique los permisos necesarios para las solicitudes de cliente. En el caso de los back-end que admiten la autenticación Microsoft Entra ID, prefiera una identidad administrada de API Management con solo los permisos que necesita. La autenticación de certificados es otra opción. Evite la autenticación básica cuando haya más opciones seguras disponibles. Para obtener más información, consulte Autenticación y autorización a las API en Azure API Management.

   Nota

   Si necesita claves de suscripción de API Management, no las use como sustituto de la autenticación y la autorización de nivel de recurso.

5. Configure directivas para la autenticación, el acceso entre orígenes, las transformaciones de mensajes, el filtrado de IP, los límites de velocidad y las cuotas según sea necesario. Configure el almacenamiento en caché de respuesta solo para los datos que son seguros para almacenar en caché. Aplique directivas en el ámbito adecuado y compruebe su comportamiento efectivo para cada operación.

Para más información, consulte la documentación de API Management.

Compatibilidad con desarrolladores en el lado cliente

Proporcione a los consumidores de API documentación para la autenticación, las operaciones, los parámetros, los tipos de datos y los códigos de respuesta.

Documentación de las operaciones REST para una API web

Publique una definición de OpenAPI que describa las operaciones, los parámetros, los esquemas de solicitud y respuesta de la API y los requisitos de seguridad. Manténgalo bajo control de versiones con la implementación y compruebe que coincide con el comportamiento real de la API.

Complemente la referencia de API con instrucciones para que los consumidores usen la API correctamente:

• Requisitos y permisos de autenticación para cada operación.
• Solicitudes representativas, respuestas correctas y respuestas de error.
• Reglas de validación de entrada, límites de carga, paginación y límites de tasa.
• Comportamiento del tiempo de espera, seguridad al reintentar y cualquier requisito de idempotencia.
• Estado y recuperación de resultados para operaciones de larga duración.
• Control de versiones y expectativas de compatibilidad.

Mantenga actualizada la documentación y los ejemplos cuando cambie el contrato de API.

Implementación de un SDK de cliente

Considere la posibilidad de proporcionar un SDK para consumidores de API. El SDK puede exponer métodos tipados que construyen solicitudes, analizan respuestas y muestran los errores documentados de la API.

Considere la posibilidad de generar clientes tipados a partir de la definición de OpenAPI de la API, pero valide el comportamiento generado frente al servicio. Autenticación de documentos, tiempos de espera, cancelación, paginación, respuestas de error y qué operaciones son seguras para reintentar. Mantenga alineada la directiva de compatibilidad de API y cliente. El código generado no quita la necesidad de pruebas de integración.

Supervisión de una API web

Supervise la API, sus dependencias y cualquier puerta de enlace conjuntamente. Defina los objetivos y alertas de nivel de servicio en función del impacto en el cliente en lugar de confiar solo en el estado del host.

Supervisión de una API web directamente

Use la instrumentación de OpenTelemetry para recopilar seguimientos, métricas y registros, y exportar las señales a Application Insights u otro back-end compatible. Para .NET, Node.js y la instrumentación de Python, siga las instrucciones de Microsoft OpenTelemetry Distro. Java usa la distribución de Azure Monitor OpenTelemetry. Siga las instrucciones de habilitación de OpenTelemetry específicas del lenguaje.

Señales de monitorización que describen el comportamiento de la API:

• Volumen de solicitudes, tasa de errores y percentiles de latencia por operación
• Latencia de las dependencias, fallos y tiempos de espera
• Rechazos por limitación de tasa, trabajo simultáneo y saturación de recursos
• Antigüedad de la cola de operaciones en segundo plano, tiempo de finalización, fallos y reintentos
• Eficacia de la memoria caché, cuando el almacenamiento en caché forma parte del diseño

La telemetría que una herramienta de supervisión recopila automáticamente varía en función del idioma, las bibliotecas y la configuración. Agregue instrumentación para las operaciones de dominio y el trabajo en segundo plano. No suponga que las sesiones del explorador, los roles de usuario o todos los detalles de la solicitud están disponibles automáticamente. Propagar el contexto de seguimiento a través de la puerta de enlace, la aplicación y los workers. Configure el muestreo y la retención para equilibrar las necesidades de diagnóstico, la confidencialidad de los datos y el costo de telemetría.

Utilice pruebas de disponibilidad estándar de Application Insights para comprobaciones externas periódicas cuando corresponda. Compruebe un punto de conexión de estado u operación significativo sin exponer datos confidenciales, defina alertas accionables y mantenga un runbook de respuesta.

Supervisión de una API web mediante API Management

Use las métricas, registros, análisis y diagnósticos de Azure Monitor compatibles con API Management para distinguir los errores de puerta de enlace de los errores de back-end. Correlacionar la telemetría del gateway y la aplicación, y supervisar los errores de política, la capacidad, la latencia de solicitudes y la limitación de tasa. Las señales disponibles dependen de la configuración del nivel de servicio y del gateway.

Siga las recomendaciones de observabilidad y capacidad de la guía de servicio Well-Architected para API Management.

Pasos siguientes

• Descripción general de OData en ASP.NET Core describe cómo crear servicios de API REST que se ajusten al protocolo OData mediante ASP.NET Core.
• Procedimientos recomendados de ASP.NET Core abarca la E/S asincrónica, el uso de recursos y el control de respuestas.
• El patrón Idempotent Consumer proporciona instrucciones de implementación para el seguimiento de los identificadores de mensajes procesados y el control de la entrega duplicada.
• La semántica HTTP define códigos de estado HTTP.
• El patrón de Request-Reply asincrónico describe los recursos de estado y trabajo en segundo plano duraderos.
• Los procedimientos recomendados de arquitectura para Azure API Management cubren la confiabilidad, la seguridad, el costo, las operaciones y el rendimiento.
• Azure Load Testing describe la generación de carga y las comprobaciones de rendimiento automatizadas.
• Habilitar OpenTelemetry proporciona instrucciones de exportación e instrumentación específicas de cada lenguaje.