OpenAPI

La API se describe mediante un documento OpenAPI: todas las operaciones, qué reciben y qué responden, con descripciones. Puede obtenerlo en

https://saas.parametriq.co.uk/openapi.json

No se necesita clave de API para el documento en sí, solo para las operaciones que describe. Es OpenAPI 3.1 e indica https://saas.parametriq.co.uk como servidor, de modo que un cliente generado a partir de él llama al servicio en esa dirección. Su esquema de seguridad, ApiKey, es su clave en el encabezado X-API-KEY (Uso de la clave de API).

Úselo para:

generar un cliente en su propio lenguaje, con una clase para cada solicitud y respuesta y un método para cada operación (véase más abajo);
probar la API en una herramienta que lea documentos OpenAPI, como Postman, Insomnia, Bruno o Swagger UI: importe la dirección anterior, establezca el encabezado X-API-KEY y envíe solicitudes;
comprobar qué recibe la API: el documento es la referencia completa, del mismo modo que las páginas de API son su guía.

Generar un cliente con Kiota

Kiota es el generador de clientes de Microsoft. Crea clientes para C#, Go, Java, PHP, Python, Ruby y TypeScript a partir de un documento OpenAPI. Para C#:

dotnet tool install --global Microsoft.OpenApi.Kiota
dotnet new console -n PiqDemo
cd PiqDemo
dotnet add package Microsoft.Kiota.Bundle
kiota generate -l CSharp -c PiqClient -n Piq.Client -d https://saas.parametriq.co.uk/openapi.json -o ./Client

Esto crea una clase PiqClient en la carpeta Client, con un generador de solicitudes para cada operación (client.Inputs, client.Measure, client.Export["pdf"] …) y una clase para cada solicitud y respuesta (TemplateRequest, DrawingRequest, MeasureResponse …). A continuación:

using Microsoft.Kiota.Abstractions.Authentication;
using Microsoft.Kiota.Abstractions.Serialization;
using Microsoft.Kiota.Http.HttpClientLibrary;
using Piq.Client;
using Piq.Client.Models;

// the key goes in the X-API-KEY header of every request
var key = Environment.GetEnvironmentVariable("PIQ_API_KEY") ?? throw new InvalidOperationException("Set PIQ_API_KEY.");
var auth = new ApiKeyAuthenticationProvider(key, "X-API-KEY", ApiKeyAuthenticationProvider.KeyLocation.Header);
var adapter = new HttpClientRequestAdapter(auth);
if (Environment.GetEnvironmentVariable("PIQ_URL") is { } url) adapter.BaseUrl = url;
var client = new PiqClient(adapter);

const string template = "L=400,\"Length\"\nW=300,\"Width\"\nP1=[L,0]\nP2=[L,W]\nP3=[0,W]\nPOLYLINE @1,[P0,P1,P2,P3],TRUE,0";

// the template's labelled variables
var inputs = await client.Inputs.PostAsync(new TemplateRequest { Template = template });
foreach (var input in inputs!.Inputs!) Console.WriteLine($"{input.Name}: {input.Label} ({input.Kind})");

// values for them: any of the template's labelled variables, by name
var values = new DrawingRequest_values { AdditionalData = { ["L"] = 500, ["W"] = 250 } };

// measured
var measured = await client.Measure.PostAsync(new DrawingRequest { Template = template, Values = values });
Console.WriteLine($"Size: {measured!.Width} x {measured.Height}");

// exported as a PDF
var pdf = await client.Export["pdf"].PostAsync(new ExportRequest
{
    Template = template, Values = new ExportRequest_values { AdditionalData = values.AdditionalData }
});
await using (var file = File.Create("box.pdf")) await pdf!.CopyToAsync(file);
Console.WriteLine("Saved box.pdf");

// a value that can't be used: refused, saying why
try
{
    await client.Measure.PostAsync(new DrawingRequest
    {
        Template = template, Values = new DrawingRequest_values { AdditionalData = { ["L"] = "long" } }
    });
}
catch (ValidationProblemDetails problem)
{
    Console.WriteLine($"{problem.Title} {problem.Detail}");
    // what is wrong, by the value it is about: each a list of messages
    foreach (var (name, messages) in problem.Errors?.AdditionalData ?? new Dictionary<string, object>())
        if (messages is UntypedArray list)
            Console.WriteLine($"  {name}: {string.Join(" ", list.GetValue().OfType<UntypedString>().Select(m => m.GetValue()))}");
}

Cómo funciona:

La clave. ApiKeyAuthenticationProvider pone su clave en el encabezado X-API-KEY de cada solicitud (solo por https).
Valores. Las variables etiquetadas de una plantilla son propias de ella, así que values no tiene campos fijos: indíquelos en AdditionalData, por nombre.
Archivos. Export (y Preview) responden con un Stream: los bytes del archivo, sea cual sea su formato.
Errores. Una solicitud rechazada lanza la descripción del problema: un ValidationProblemDetails (400), con qué está mal en qué valor en Errors, o un ProblemDetails para los demás (404, 409, 422, 502 …).

Vuelva a ejecutar kiota generate cuando cambie la API, para actualizar el cliente. Para otro lenguaje, indique su nombre con -l (Go, Java, PHP, Python, Ruby, TypeScript) y añada los paquetes de Kiota de ese lenguaje, que enumera kiota info -l <language>.

Otros generadores

A cualquier generador de OpenAPI se le puede dar la misma dirección:

NSwag (C# y TypeScript): nswag openapi2csclient /input:https://saas.parametriq.co.uk/openapi.json /output:PiqClient.cs /namespace:Piq.Client.
OpenAPI Generator (la mayoría de los lenguajes): npx @openapitools/openapi-generator-cli generate -i https://saas.parametriq.co.uk/openapi.json -g python -o piq-client, donde -g indica el lenguaje (typescript-fetch, java, go, php, ruby, csharp …).

Un cliente generado necesita su clave en el encabezado X-API-KEY, como toda solicitud: cada generador tiene su propia forma de indicarla (una opción de clave de API o un encabezado predeterminado).

Si prefiere no generar nada, la API es HTTPS y JSON sin más: consulte los Clientes para ver un ejemplo completo en cada uno de varios lenguajes, usando solo sus propios clientes HTTP.

Consulte también: API, Clientes, Uso de la clave de API.