Guides
Build a complete API client
Use auth, REST, OpenAPI, GraphQL, gRPC, SDKs, realtime, errors, idempotency, and observability together.
RESTREST controller atlasEvery controller-backed endpoint with parameters, request examples, responses, errors, and samples.RESTREST API modelBase URLs, resource conventions, pagination, idempotency, error envelopes, OpenAPI discovery, and examples.OpenAPIOpenAPI & SwaggerSpec discovery, operation IDs, schema projection, Swagger UI behavior, and client generation.GraphQLGraphQL referenceCompiled SDL, query and mutation shapes, pagination, filters, subscriptions, errors, and examples.gRPCgRPC referenceProto services, metadata, streaming, status mapping, deadlines, reflection, and generated clients.RealtimeRealtime & eventsWebSocket, SSE, event envelopes, subscription filters, replay, and field-name-only delivery.WebhooksWebhooks referenceInbound and outbound delivery, signatures, retries, replay, idempotency, and receiver contracts.MCPMCP referenceJSON-RPC methods, resource metadata, token model, tools, resources, prompts, errors, and observability.SDKSDK method referenceEvery client method across TypeScript, Python, C#, Go, and Rust with inputs, returns, and errors.ErrorsErrors referenceCanonical error envelopes, HTTP status mapping, machine-readable codes, reason codes, and correlation IDs.LimitsLimits & quotasRate limits, hard and soft quotas, budget enforcement, usage metering, and retry guidance.
1. Create a typed client
const vadyl = createClient({
apiUrl: "https://api.vadyl.app/v1",
token: process.env.VADYL_TOKEN!,
tenant: "acme",
project: "billing",
});2. Read through SDK, REST, GraphQL, or gRPC
SDK: vadyl.orders.list({ filter: { status: { eq: "paid" } } })
REST: GET /v1/orders?filter={"status":{"eq":"paid"}}
GraphQL: query { orders(filter:{status:{eq:PAID}}) { edges { node { id } } } }
gRPC: OrderService/List { filter: { status: [ORDER_STATUS_PAID] } }3. Write with idempotency
POST /v1/orders
Idempotency-Key: cart:cart_123:checkout
{ "customerId": "cus_123", "total": "29.99", "currency": "USD" }
HTTP/1.1 201 Created
{ "id": "ord_123", "status": "pending" }4. Subscribe without leaking values
const sub = vadyl.orders.subscribe({ filter: { status: { eq: "paid" } } });
for await (const evt of sub.events()) {
// evt.changedFields contains field names only. Re-read for values.
const order = await vadyl.orders.read(evt.entityId);
}5. Handle errors and explain them
try {
await vadyl.orders.update(order.id, patch, { ifMatch: order.concurrencyToken });
} catch (err) {
if (err.code === "CONFLICT") {
const fresh = await vadyl.orders.read(order.id);
// merge and retry if still intended
}
console.log(err.reasonCode, err.correlationId, err.explainUrl);
}