Connecting your back-end system
Typed messages, .NET, TypeScript, Java and Python contracts, and ready-made adapters and clients for .NET Framework, Java, Node.js and Python applications.
Your back end talks to Archr.Hermod through the message queue, in plain JSON. A request message says which
operation was called and carries the path and query parameters, the body, the correlation id, the deadline,
and who is calling with the attributes you gave that caller. The back end answers with
{ correlationId, status, headers, body } on the reply topic. Any language that can read
and write messages on NATS or Kafka can do it.
Contracts
So that nobody has to write the message classes by hand, Archr.Hermod produces them from the papiNet documents:
- a .NET Standard 2.0 library, so it works from .NET Framework 4.6.1 and later as well as from current .NET, with a class for every schema in every bundled papiNet version and a table of the operations with their topics;
- the same as TypeScript interfaces, in a package for Node.js;
- the same as Python typed dictionaries (
TypedDict), one module for each version, so a message stays a plaindictand a type checker such as mypy or pyright knows its keys; - the same as Java classes, for Java 8 and later, named exactly as the .NET and TypeScript ones, with an
Operationsclass that lists every operation with its topics and the classes of its request and response; - the JSON Schema of the request and reply messages, for any other language.
The Admin pages offer a download of the contracts for any version that has been registered, including one added after the library was built. The zip holds the C#, TypeScript, Java and Python classes of that version (the Java ones as a small Maven project that builds into a jar, and the Python ones as a package folder), the JSON Schemas, the papiNet document and the list of operations with their topics.
A ready-made adapter for .NET Framework
A back end such as an older .NET Framework application should not have to write queue code. The host adapter subscribes to Kafka for the operations you have handlers for, calls your handler with the request, and publishes the reply:
var adapter = PapinetHostAdapter.ForKafka(settings);
adapter.Handle(Operations.GetSupplierOrders, call =>
PapinetResponse.Ok(repository.List(call.Attribute("AppId"), call.Query("isActive"))));
adapter.Start();
A handler sees the parameters, the caller's attributes, the body as its generated class, and a cancellation token that fires at the deadline. The adapter skips requests whose caller has already given up, reconnects if the broker goes away, and answers a handler that fails with a prompt error instead of leaving the caller to time out. Delivery is at least once, so a handler that changes data should be safe to run twice; the correlation id identifies a repeat. The adapter has been exercised in a .NET Framework 4.8 process answering Archr.Hermod's API over a real Kafka broker. The same package holds a client for the other direction, described under Calling partners below.
A ready-made adapter for Java applications
A back end written in Java should not have to write queue code either. The Java adapter is part of Archr.Hermod's Java toolkit, which runs on Java 8 and later and also holds the Java contracts above and a client for calling trading partners. Like the .NET Framework adapter, it subscribes to Kafka for the operations you have handlers for, calls your handler with the request, and publishes the reply:
PapinetHostAdapter adapter = PapinetHostAdapter.forKafka(kafka, new PapinetHostAdapterOptions(), log);
adapter.handle(Operations.GET_SUPPLIER_ORDERS, call ->
PapinetResponse.ok(repository.list(call.attribute("AppId"), call.query("isActive"))));
adapter.start();
A handler sees the same things a .NET handler does: the parameters, the caller's attributes and the body as its generated class. When the caller's deadline passes, the handler's thread is interrupted and nothing it answers is sent. The adapter skips requests whose caller has already given up, reconnects if the broker goes away, and answers a handler that fails with a prompt error. The rules for delivery are the same too: at least once, so a handler that changes data should be safe to run twice.
A ready-made adapter for Node.js applications
The TypeScript package, @archr/papinet, does the same for a back end written for Node.js: it holds the contracts above, an adapter
that serves the API, and a client for calling trading partners. The adapter subscribes to Kafka for the operations you have handlers for,
calls your handler with the request, and publishes the reply:
const adapter = PapinetHostAdapter.forKafka(kafka, { maxConcurrency: 4 }, log);
adapter.handle(operations.getSupplierOrders, async (call) =>
PapinetResponse.ok(await repository.list(call.attribute("AppId"), call.query("isActive"))));
adapter.start();
The handler's answer is checked against the operation when you compile: the generated types say what each operation returns. A handler sees the
parameters, the caller's attributes and the body, and an AbortSignal that fires at the deadline; the adapter does not wait for a handler that
is still running then. It skips requests whose caller has already given up, reconnects if the broker goes away, and answers a handler that fails with a
prompt error. Delivery is at least once, as for the others. The adapter has been exercised in a Node.js process answering Archr.Hermod's API over a real
Kafka broker; it uses Kafka through kafkajs and has been built and tested on Node.js 25.
A ready-made adapter for Python applications
The Python package, archr-papinet, is the same toolkit in the way Python programmers expect it: handlers are decorated functions, messages are
plain dictionaries with type hints, logging goes through the standard logging module, and the client and the adapter are context managers.
The adapter subscribes to Kafka for the operations you have handlers for, calls your handler with the request, and publishes the reply:
adapter = HostAdapter.for_kafka(kafka, max_concurrency=4)
@adapter.handle(v4.GET_SUPPLIER_ORDERS)
def list_orders(call):
orders = repository.list(call.attribute("AppId"), call.query("isActive"))
return Response.ok(orders) if orders else Response.no_content()
adapter.serve_forever()
A handler sees the parameters, the caller's attributes and the body, and can ask whether the caller has given up. The adapter does not wait for a handler that
is still running at the deadline, skips requests whose caller has already given up, reconnects if the broker goes away, and answers a handler that fails with a
prompt error. Delivery is at least once, as for the others. It runs handlers in threads (several at a time if you ask for it) and uses Kafka through
confluent-kafka; it has been exercised in a Python process answering Archr.Hermod's API over a real Kafka broker, and built and tested on Python 3.9 and 3.12.
Calling partners
The clients are the other direction: your application names the partner and the operation, and Archr.Hermod makes the call through the outbound hub. The same call in Java, C#, TypeScript and Python:
OutboundCall call = client.call(Operations.GET_LOGISTICS_DELIVERY_NOTES, "BAFOR").query("limit", "20").execute();
if (call.isSucceeded()) {
ListOfLogisticsDeliveryNotes notes = call.body();
}
var call = await client.Call(Operations.GetLogisticsDeliveryNotes, "BAFOR").Query("limit", "20").ExecuteAsync<ListOfLogisticsDeliveryNotes>();
if (call.Succeeded) { var notes = call.Body; }
const call = await client.call(operations.getLogisticsDeliveryNotes, "BAFOR").query("limit", 20).execute();
if (call.succeeded) { const notes = call.body; }
call = client.call(v4.GET_LOGISTICS_DELIVERY_NOTES, "BAFOR", query={"limit": 20})
if call.succeeded:
notes = call.body
The client holds no address, key or certificate for the partner; Archr.Hermod does. A call that did not work is not an exception: its outcome (delivered, refused, unavailable, timeout, failed) says what happened, and a partner's 404 is still a delivered answer.
Today all four use Kafka as their message queue. Each adapter and each client has been exercised in a process of its own kind (.NET Framework 4.8, Java 8, Node.js, Python) answering Archr.Hermod's API or calling a partner through the outbound hub, over a real Kafka broker.
Step-by-step guides
The SDK guides take each job step by step, with code in C#, Java, TypeScript and Python: what the SDK holds for each language and the messages they share, serving the papiNet API from your back end, and calling trading partners from your application.
Try it without writing code
The papiNet Client, a small web application included with Archr.Hermod, calls trading partners' APIs through the outbound hub and shows the answers as forms: for example a delivery note with its parties, legs, line items and the individual packages on each line.