Creación de API web JSON desde gRPC

Por James Newton-King

gRPC es una forma moderna de comunicarse entre aplicaciones. gRPC usa HTTP/2, streaming, Protobuf y contratos de mensaje para crear servicios en tiempo real de alto rendimiento.

Una limitación de gRPC es que no se puede usar en todas las plataformas. Los exploradores no son totalmente compatibles con HTTP/2, por lo que REST y JSON son la manera principal de obtener datos en aplicaciones de explorador. Incluso con las ventajas que aporta gRPC, REST y JSON ocupan un lugar importante en las aplicaciones modernas. La compilación de API web JSON y gRPC agrega una sobrecarga no deseada al desarrollo de aplicaciones.

En este documento se explica cómo crear API web JSON con servicios gRPC.

API HTTP de gRPC

La API HTTP de gRPC es una extensión experimental para ASP.NET Core que crea API JSON de RESTful para servicios gRPC. Una vez configurada, la API HTTP de gRPC permite que las aplicaciones llamen a servicios gRPC con conceptos conocidos de HTTP:

• Verbos HTTP
• Enlace de parámetros de dirección URL
• Solicitudes y respuestas JSON

gRPC también se puede usar para llamar a servicios.

Uso

1. Agregue una referencia de paquete a Microsoft.AspNetCore.Grpc.HttpApi.
2. Registre los servicios en Startup.cs con AddGrpcHttpApi.
3. Agregue los archivos google/api/http.proto y google/api/annotations.proto al proyecto.
4. Anote los métodos gRPC en los archivos .proto con enlaces y rutas HTTP:

syntax = "proto3";

import "google/api/annotations.proto";

package greet;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };
  }
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

El método gRPC SayHello ya se puede invocar como gRPC+protobuf y como una API HTTP:

• Solicitud: HTTP/1.1 GET /v1/greeter/world
• Respuesta: { "message": "Hello world" }

Los registros de servidor muestran que un servicio gRPC ejecuta la llamada HTTP. La API HTTP de gRPC asigna la solicitud HTTP entrante a un mensaje de gRPC y, luego, convierte el mensaje de respuesta en JSON.

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/1.1 GET https://localhost:5001/v1/greeter/world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /v1/greeter/{name}'
info: Server.GreeterService[0]
      Sending hello to world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /v1/greeter/{name}'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 1.996ms 200 application/json

Este es un ejemplo básico. Consulte HttpRule para conocer más opciones de personalización.

Habilitación de la compatibilidad con Swagger/OpenAPI

Swagger (OpenAPI) es una especificación independiente del lenguaje que sirve para describir API REST. La API HTTP de gRPC puede integrarse con Swashbuckle para generar un punto de conexión de Swagger para servicios gRPC RESTful. Por lo tanto, el punto de conexión de Swagger se puede usar con la interfaz de usuario de Swagger y otras herramientas.

Para habilitar Swagger con la API HTTP de gRPC:

1. Agregue una referencia de paquete a Microsoft.AspNetCore.Grpc.Swagger.
2. Configure Swashbuckle en Startup.cs. El método AddGrpcSwagger configura Swashbuckle para incluir los puntos de conexión de la API HTTP de gRPC.

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddGrpcHttpApi();
    
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
    services.AddGrpcSwagger();
}

public void Configure(IApplicationBuilder app)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<GreeterService>();
    });
}

Para confirmar que Swashbuckle genera Swagger para los servicios gRPC RESTful, inicie la aplicación y vaya a la página de la interfaz de usuario de Swagger:

API HTTP de gRPC frente a gRPC-Web

Tanto la API HTTP de gRPC como gRPC-Web permiten llamar a servicios gRPC desde un explorador, aunque de manera diferente:

• gRPC-Web permite a las aplicaciones de explorador llamar a servicios gRPC desde el explorador con el cliente gRPC-Web y Protobuf. gRPC-Web requiere que la aplicación de explorador genere un cliente gRPC y tiene la ventaja de que envía mensajes de Protobuf pequeños y rápidos.
• La API HTTP de gRPC permite a las aplicaciones de explorador llamar a servicios gRPC como si fueran API de RESTful con JSON. No es necesario que la aplicación de explorador genere un cliente gRPC o que disponga de información sobre gRPC.

No se crea ningún cliente generado para la API HTTP de gRPC. Se puede llamar al servicio Greeter anterior mediante las API de JavaScript del explorador:

var name = nameInput.value;

fetch("/v1/greeter/" + name).then(function (response) {
  response.json().then(function (data) {
    console.log("Result: " + data.message);
  });
});

Estado experimental

La API HTTP de gRPC es un experimento. Todavía no está completa y no se admite. Nos interesa esta tecnología y las capacidades que ofrece a los desarrolladores de aplicaciones para crear rápidamente servicios gRPC y JSON al mismo tiempo. No hay ningún compromiso para completar la API HTTP de gRPC.

Queremos valorar el interés que tienen los desarrolladores por la API HTTP de gRPC. Si le atrae la API HTTP de gRPC, envíenos sus comentarios.

grpc-gateway

grpc-gateway es otra tecnología para crear API JSON de RESTful desde servicios gRPC. Usa las mismas anotaciones .proto para asignar conceptos HTTP a servicios gRPC.

La principal diferencia entre grpc-gateway y la API HTTP de gRPC es que grpc-gateway usa la generación de código para crear un servidor proxy inverso. El proxy inverso traslada las llamadas de RESTful a gRPC y, luego, las envía al servicio gRPC.

Para obtener información sobre la instalación y el uso de grpc-gateway, consulte el archivo LÉAME de grpc-gateway.

Recursos adicionales

• Documentación de google.api.HttpRule
• Uso de gRPC en aplicaciones de explorador