Technical Reference

SDK guide 2: Handling inbound papiNet API calls and integrating with your business applications

Step by step, with code in Java, C#, TypeScript and Python: connect to the queue, write a handler for each operation, answer with the right status, and find out why a caller gets 502 or 504.

Show the examples in

This is the first job: partners call Archr.Hermod's papiNet API and your back end answers. The pieces you write are one handler per papiNet operation you serve; the queue, the deadline and the reply are done for you. Read guide 1 first for the messages.

1. Decide what you serve

papiNet 4.0.0 has lists (GET /supplier-orders), single documents (GET /supplier-orders/{id}) and pushes (POST /logistics-goods-receipts). Serve the ones your system has data for. An operation without a handler is not subscribed to: its requests wait on the queue and the caller gets 504, which is the honest answer from a system that does not serve it yet.

2. Add the SDK

C#

Reference Hermod.PapiNet.HostAdapter; it brings Hermod.PapiNet.Contracts and Confluent.Kafka. It targets .NET Standard 2.0, so a .NET Framework 4.6.1 application can use it. On .NET Framework Confluent.Kafka needs its native library: the librdkafka.redist package copies it next to your application. A packages.config project should reference Confluent.Kafka itself, so that the folders arrive.

Java

Add the adapter (it brings the contracts and the Kafka client):

pom.xml
<dependency>
  <groupId>software.archr.papinet</groupId>
  <artifactId>archr-papinet-host-adapter</artifactId>
  <version>1.0.0</version>
</dependency>

Java 8 and later. Until the jars are on a public repository, build them with ./mvnw install in the toolkit's source folder.

TypeScript

Install the toolkit (it brings kafkajs, the Kafka client):

shell
npm install ./archr-papinet-1.0.0.tgz

Built and tested on Node.js 25 (the package asks for Node.js 18 or later). Until it is on npm, build the tarball with npm pack in the toolkit's source folder. The version's module (@archr/papinet/V4_0_0) has an interface for every papiNet schema and an operations table that gives each operation its topics and the types of its bodies, so a handler's answer is checked against the operation when you compile.

Python

Install the toolkit (it brings confluent-kafka, the Kafka client, which has wheels for the usual platforms):

shell
pip install ./python

Python 3.9 and later (built and tested on 3.9 and 3.12). Until it is on PyPI, install it from the toolkit's source folder. Each papiNet version is a module (archr_papinet.versions.v4_0_0) with a TypedDict for every schema and a constant for every operation, so mypy or pyright checks a handler's answer against the operation. A message stays a plain dict, as JSON does in Python: the keys keep papiNet's spelling (supplierOrderId), and the toolkit's own names are the usual Python ones (call.path_parameter_uuid, adapter.start()).

3. Connect to the queue

Use the Kafka cluster Archr.Hermod uses. Give your application a consumer group of its own for each environment (test, production): all running copies of the application in one environment share it, so each request goes to one of them. Two environments sharing a cluster and a group would answer each other's requests. Keep the password in your own secret store, not in a file that is checked in. Archr.Hermod creates the request topics of the operations it serves; if a platform team provisions topics, the ones you need are papinet.v4-0-0.<operation>.request (read) and .response (write).

Java

Java
static KafkaPapinetSettings kafkaSettings() {
    return new KafkaPapinetSettings()
            .setBootstrapServers("broker1:9092,broker2:9092")
            .setGroupId("erp-papinet-prod")                       // one per environment: all copies of the application in it share the work
            .setSaslUsername(System.getenv("PAPINET_KAFKA_USER"))  // leave both out for a cluster without a login
            .setSaslPassword(System.getenv("PAPINET_KAFKA_PASSWORD"));
}

TypeScript

TypeScript
export const kafkaSettings: KafkaPapinetSettings = {
    bootstrapServers: "broker1:9092,broker2:9092",
    groupId: "erp-papinet-prod",                       // one per environment: all copies of the application in it share the work
    saslUsername: process.env.PAPINET_KAFKA_USER,       // leave both out for a cluster without a login
    saslPassword: process.env.PAPINET_KAFKA_PASSWORD,
};

Python

Python
kafka = KafkaSettings(
    "broker1:9092,broker2:9092",
    group_id="erp-papinet-prod",                        # one per environment: all copies of the application in it share the work
    sasl_username=os.environ.get("PAPINET_KAFKA_USER"),  # leave both out for a cluster without a login
    sasl_password=os.environ.get("PAPINET_KAFKA_PASSWORD"),
)

In C# the same settings are the first lines of the example in step 4 (KafkaPapinetSettings).

4. Write the handlers

A handler gets the request and returns the answer. It sees the path and query parameters, who is calling with the attributes the administrator gave that caller (for Apollo, AppId decides whose data a request is about), and the body as its generated class. Three kinds cover nearly everything: a list, one document, and a push.

C#

C#
public static PapinetHostAdapter Serve(IOrderRepository orders, IReceiptRepository receipts, IPapinetLog log)
{
    var kafka = new KafkaPapinetSettings
    {
        BootstrapServers = "broker1:9092,broker2:9092",
        GroupId = "apollo-papinet-prod",                              // one per environment: all copies of the application in it share the work
        SaslUsername = Environment.GetEnvironmentVariable("PAPINET_KAFKA_USER"),       // leave both out for a cluster without a login
        SaslPassword = Environment.GetEnvironmentVariable("PAPINET_KAFKA_PASSWORD"),
    };

    var adapter = PapinetHostAdapter.ForKafka(kafka, new PapinetHostAdapterOptions { MaxConcurrency = 4 }, log);

    adapter
        // A list: the caller's AppId (set by Archr.Hermod's administrator) decides whose data it is.
        .Handle(Operations.GetSupplierOrders, call =>
        {
            var page = orders.List(call.Attribute("AppId"), call.Query("isActive"), call.Offset, call.Limit(20));
            return page.Count == 0
                ? PapinetResponse.NoContent()
                : PapinetResponse.Ok(new ListOfSupplierOrders { Items = page, Count = page.Count });
        })
        // One document: a missing one is a 404, not an error.
        .Handle(Operations.GetSupplierOrdersSupplierOrderId, async (call, ct) =>
        {
            var order = await orders.FindAsync(call.Attribute("AppId"), call.PathParameterGuid("supplierOrderId"), ct);
            return order == null ? PapinetResponse.NotFound("No such order.") : PapinetResponse.Ok(order);
        })
        // A push: read the body as its class, and be repeatable (the queue delivers at least once).
        .Handle(Operations.PostLogisticsGoodsReceipts, call =>
        {
            var receipt = call.ReadBody<LogisticsGoodsReceiptById>();
            if (!receipts.AlreadyStored(call.Attribute("AppId"), call.CorrelationId))
                receipts.Store(call.Attribute("AppId"), call.CorrelationId, receipt);
            return PapinetResponse.Ok();
        });

    adapter.Start();   // returns at once; the listening is done in the background
    return adapter;    // at shutdown: await adapter.StopAsync();   (requests in progress finish first)
}

Java

Java
static PapinetHostAdapter serve(OrderRepository orders, ReceiptRepository receipts, PapinetLog log) {
    PapinetHostAdapter adapter = PapinetHostAdapter.forKafka(kafkaSettings(), new PapinetHostAdapterOptions().setMaxConcurrency(4), log);

    adapter
        // A list: the caller's AppId (set by Archr.Hermod's administrator) decides whose data it is.
        .handle(Operations.GET_SUPPLIER_ORDERS, call -> {
            List<ListOfSupplierOrdersItemsItem> page = orders.list(call.attribute("AppId"), call.query("isActive"), call.offset(), call.limit(20));
            if (page.isEmpty()) {
                return PapinetResponse.noContent();
            }
            ListOfSupplierOrders list = new ListOfSupplierOrders();
            list.setItems(page);
            list.setCount(page.size());
            return PapinetResponse.ok(list);
        })
        // One document: a missing one is a 404, not an error.
        .handle(Operations.GET_SUPPLIER_ORDERS_SUPPLIER_ORDER_ID, call -> {
            SupplierOrderById order = orders.find(call.attribute("AppId"), call.pathParameterUuid("supplierOrderId"));
            return order == null ? PapinetResponse.notFound("No such order.") : PapinetResponse.ok(order);
        })
        // A push: read the body as its class, and be repeatable (the queue delivers at least once).
        .handle(Operations.POST_LOGISTICS_GOODS_RECEIPTS, call -> {
            LogisticsGoodsReceiptById receipt = call.readBody(LogisticsGoodsReceiptById.class);
            if (!receipts.alreadyStored(call.attribute("AppId"), call.getCorrelationId())) {
                receipts.store(call.attribute("AppId"), call.getCorrelationId(), receipt);
            }
            return PapinetResponse.ok();
        });

    adapter.start();   // returns at once; the listening is done in the background
    return adapter;
}

TypeScript

TypeScript
export function serve(orders: OrderRepository, receipts: ReceiptRepository, log: PapinetLog): PapinetHostAdapter {
    const adapter = PapinetHostAdapter.forKafka(kafkaSettings, { maxConcurrency: 4 }, log);

    adapter
        // A list: the caller's AppId (set by Archr.Hermod's administrator) decides whose data it is.
        .handle(operations.getSupplierOrders, async (call) => {
            const page = await orders.list(call.attribute("AppId"), call.query("isActive"), call.offset, call.limit(20));
            if (page.length === 0) return PapinetResponse.noContent();
            const list: ListOfSupplierOrders = { count: page.length, items: page };
            return PapinetResponse.ok(list);
        })
        // One document: a missing one is a 404, not an error.
        .handle(operations.getSupplierOrdersSupplierOrderId, async (call) => {
            const order = await orders.find(call.attribute("AppId"), call.pathParameterUuid("supplierOrderId"));
            return order ? PapinetResponse.ok(order) : PapinetResponse.notFound("No such order.");
        })
        // A push: the body is the generated type, and handling it must be repeatable (the queue delivers at least once).
        .handle(operations.postLogisticsGoodsReceipts, async (call) => {
            const appId = call.attribute("AppId");
            if (!(await receipts.alreadyStored(appId, call.correlationId))) {
                await receipts.store(appId, call.correlationId, call.requireBody());
            }
            return PapinetResponse.ok();
        });

    adapter.start();   // returns at once; the listening is done in the background
    return adapter;
}

Python

Python
def build_adapter(orders: OrderRepository, receipts: ReceiptRepository) -> HostAdapter:
    adapter = HostAdapter.for_kafka(kafka, max_concurrency=4)

    # A list: the caller's AppId (set by Archr.Hermod's administrator) decides whose data it is.
    @adapter.handle(v4.GET_SUPPLIER_ORDERS)
    def list_orders(call: Call[None]) -> Response[v4.ListOfSupplierOrders]:
        page = orders.list(call.attribute("AppId"), call.query("isActive"), call.offset, call.limit(20))
        if not page:
            return Response.no_content()
        return Response.ok({"count": len(page), "items": page})

    # One document: a missing one is a 404, not an error.
    @adapter.handle(v4.GET_SUPPLIER_ORDERS_SUPPLIER_ORDER_ID)
    def get_order(call: Call[None]) -> Response[v4.SupplierOrderById]:
        order = orders.find(call.attribute("AppId"), call.path_parameter_uuid("supplierOrderId"))
        return Response.ok(order) if order else Response.not_found("No such order.")

    # A push: the body is a dict typed by the operation, and handling it must be repeatable (the queue delivers at least once).
    @adapter.handle(v4.POST_LOGISTICS_GOODS_RECEIPTS)
    def receive_receipt(call: Call[v4.LogisticsGoodsReceiptById]) -> Response[t.Any]:
        app_id = call.attribute("AppId")
        if not receipts.already_stored(app_id, call.correlation_id):
            receipts.store(app_id, call.correlation_id, call.require_body())
        return Response.ok()

    return adapter

5. Answer with the right status

Your handlerThe caller gets
Returns the document or the list200 with the body
Returns "no content" for a list with nothing in it204
Returns "not found" for a document that does not exist404, with your text as the problem's detail: write it for the caller
Returns "bad request" with a reason, or the id in the path is not an identifier400
Throws, returns nothing, or returns a body of the wrong classThe adapter answers 500; Archr.Hermod answers its caller 502 and logs it. The exception text stays in your log and is never sent.
Answers a status the papiNet document does not declare502, and Archr.Hermod logs your value
Is still running when the deadline passesNothing is sent: the caller was told 504

C#

C#
public static void Statuses(IOrderRepository orders, PapinetHostAdapter adapter)
{
    adapter.Handle(Operations.GetSupplierOrdersSupplierOrderId, async (call, ct) =>
    {
        if (call.Attribute("AppId") == null)
            return PapinetResponse.BadRequest("The caller has no AppId.");        // 400, with a reason the caller can act on

        var order = await orders.FindAsync(call.Attribute("AppId"), call.PathParameterGuid("supplierOrderId"), ct);   // a bad id is a 400 by itself
        if (order == null)
            throw new PapinetStatusException(404, "No such order.");               // the same as returning NotFound, from deep inside your code

        return PapinetResponse.Ok(order);                                          // any other exception becomes 500: Archr.Hermod tells its caller 502
    });
    // ct is cancelled when the caller's deadline passes: pass it to your database and HTTP calls so they stop too.
}

Java

Java
static void statuses(OrderRepository orders, PapinetHostAdapter adapter) {
    adapter.handle(Operations.GET_SUPPLIER_ORDERS_SUPPLIER_ORDER_ID, call -> {
        if (call.attribute("AppId") == null) {
            return PapinetResponse.badRequest("The caller has no AppId.");        // 400, with a reason the caller can act on
        }
        SupplierOrderById order = orders.find(call.attribute("AppId"), call.pathParameterUuid("supplierOrderId"));   // a bad id is a 400 by itself
        if (order == null) {
            throw new PapinetStatusException(404, "No such order.");               // the same as returning notFound, from deep inside your code
        }
        if (call.isCancelled()) {
            return PapinetResponse.noContent();                                    // the caller has given up: whatever you answer is thrown away
        }
        return PapinetResponse.ok(order);                                          // any other exception becomes 500: Archr.Hermod tells its caller 502
    });
}

TypeScript

TypeScript
export function statuses(orders: OrderRepository, adapter: PapinetHostAdapter): void {
    adapter.handle(operations.getSupplierOrdersSupplierOrderId, async (call) => {
        if (call.attribute("AppId") === undefined) {
            return PapinetResponse.badRequest("The caller has no AppId.");        // 400, with a reason the caller can act on
        }
        const order = await orders.find(call.attribute("AppId"), call.pathParameterUuid("supplierOrderId"));   // a bad id is a 400 by itself
        if (!order) {
            throw new PapinetStatusError(404, "No such order.");                   // the same as returning notFound, from deep inside your code
        }
        if (call.signal.aborted) {
            return PapinetResponse.noContent();                                    // the caller has given up: whatever you answer is thrown away
        }
        return PapinetResponse.ok(order);                                          // any other exception becomes 500: Archr.Hermod tells its caller 502
    });
}

Python

Python
def register_with_statuses(orders: OrderRepository, adapter: HostAdapter) -> None:
    @adapter.handle(v4.GET_SUPPLIER_ORDERS_SUPPLIER_ORDER_ID)
    def get_order(call: Call[None]) -> Response[v4.SupplierOrderById]:
        if call.attribute("AppId") is None:
            return Response.bad_request("The caller has no AppId.")                        # 400, with a reason the caller can act on
        order = orders.find(call.attribute("AppId"), call.path_parameter_uuid("supplierOrderId"))   # a bad id is a 400 by itself
        if order is None:
            raise StatusError(404, "No such order.")                                       # the same as returning not_found, from deep inside your code
        call.raise_if_cancelled()                                                          # the caller has given up: whatever you answer is thrown away
        return Response.ok(order)                                                          # any other exception becomes 500: Archr.Hermod tells its caller 502

6. Be safe to run twice, and stop when the caller has gone

7. Logging

The adapters depend on no logging library. They write through a one-method interface that you put in front of your own logger, and report each failure, each skipped request and each loss of the broker there.

C#

C#
public static IPapinetLog TraceLog() =>
    PapinetLog.From((level, message, error) => System.Diagnostics.Trace.WriteLine(level + " " + message + (error == null ? string.Empty : " | " + error)));

For a trial, PapinetLog.Console() writes to the console.

Java

Java
static PapinetLog slf4jLog() {
    final Logger slf4j = LoggerFactory.getLogger("papinet");
    return (level, message, error) -> {
        switch (level) {
            case DEBUG:
                slf4j.debug(message, error);
                break;
            case INFORMATION:
                slf4j.info(message, error);
                break;
            case WARNING:
                slf4j.warn(message, error);
                break;
            default:
                slf4j.error(message, error);
        }
    };
}

For a trial, PapinetLog.console() writes to the standard error stream.

TypeScript

TypeScript
export function pinoLog(pino: { debug(o: object, m: string): void; info(o: object, m: string): void; warn(o: object, m: string): void; error(o: object, m: string): void }): PapinetLog {
    return {
        write(level, message, error) {
            const where = level === "debug" ? pino.debug : level === "information" ? pino.info : level === "warning" ? pino.warn : pino.error;
            where.call(pino, { err: error }, message);
        },
    };
}

For a trial, papinetLog.console() writes to the console.

Python

Python
def set_up_logging() -> None:
    # The toolkit writes through the standard `logging` module, to loggers under "archr_papinet": nothing to adapt, just configure it as you do for the rest of the application.
    logging.basicConfig(format="%(asctime)s %(levelname)s %(name)s %(message)s")
    logging.getLogger("archr_papinet").setLevel(logging.INFO)    # DEBUG adds a line for every request answered

8. Start it, and stop it

Start once, when your application starts, and stop when it stops. Starting returns at once; listening happens in the background, and if the broker is unreachable the adapter says so in the log and tries again, for ever. Stopping lets requests in progress finish, and leaves the requests it has not started on the queue for the next start. A process that is not always running (a job that starts for each run) is the wrong place: it must be running to answer within the deadline.

C#

Where to start it: a Windows service's OnStart, Application_Start, the start of a worker. The example in step 4 returns the adapter; at shutdown call await adapter.StopAsync(). In IIS an application-pool recycle stops and starts it, and requests in progress finish first.

Java

Java
static void runUntilShutdown(final PapinetHostAdapter adapter) {
    // Start once, when the application starts; close when it stops (a servlet context listener, a Spring @PreDestroy, a shutdown hook).
    Runtime.getRuntime().addShutdownHook(new Thread(new Runnable() {
        @Override
        public void run() {
            adapter.close();   // requests in progress finish first; the ones not started wait on the queue
        }
    }));
    System.out.println(adapter.getStatus());   // RUNNING: received 0, answered 0, failed 0, skipped 0
}

TypeScript

TypeScript
export function runUntilShutdown(adapter: PapinetHostAdapter): void {
    // Start once, when the application starts; close when it stops.
    for (const signal of ["SIGINT", "SIGTERM"] as const) {
        process.once(signal, () => {
            adapter.close().then(() => process.exit(0));   // requests in progress finish first; the ones not started wait on the queue
        });
    }

    console.log(adapter.status());   // { state: 'running', topics: [...], received: 0, answered: 0, failed: 0, skipped: 0 }
}

Python

Python
def run(adapter: HostAdapter) -> None:
    # A service whose only job is this: start, wait for Ctrl+C or SIGTERM, then close (requests in progress finish first; the ones not started wait on the queue).
    adapter.serve_forever()


def run_inside_an_application(adapter: HostAdapter) -> None:
    # Inside a larger application (a Django or Flask worker, a scheduler): start when it starts, close when it stops. `with adapter:` does both.
    with adapter:
        print(adapter.status())      # AdapterStatus(state='running', received=0, answered=0, failed=0, skipped=0, ...)
        ...                          # the application's own work

9. Try it

  1. In the Admin pages, papiNet API, check that the version is live and the operation is switched on. An operation that is off has no route: callers get 404.
  2. Make sure no development responder is answering the same topics. It answers every request with papiNet's own example data so that partners can start before your back end is ready; switched on beside a real back end, it competes with it.
  3. Call the API as a partner would, with a partner key in the X-Api-Key header:
    shell
    curl -H "X-Api-Key: <partner key>" "https://<your gateway>/papinet/v4/supplier-orders?isActive=true"
    or use the explorer on the version's Admin page, which makes the same call.
  4. Your adapter's status shows what it has done: C# adapter.GetStatus(), Java adapter.getStatus(), TypeScript and Python adapter.status() (state, topics, counts of received, answered, failed and skipped, the last error).

10. Without the adapter

The adapter is a convenience. If you would rather read the queue with your own code (another Kafka client, another queue), what it does is: read the request, call your code, and publish the reply where the request said, with the correlation id and the reply id copied from it. The message types do the parsing and the reply:

C#

C#
public static void ReadAndAnswerWithoutTheAdapter(byte[] payload, Action<string, byte[], IDictionary<string, string>> publish)
{
    // A message arrived on papinet.v4-0-0.get-supplier-orders-supplierOrderId.request
    var request = PapinetRequest<JToken>.Read(payload);
    var operation = Operations.Find(request.Operation);
    var orderId = request.GetPathParameter("supplierOrderId");
    var appId = request.Caller.GetAttribute("AppId");

    var order = new SupplierOrderById { /* fill it in from your system */ };
    var reply = PapinetReply<SupplierOrderById>.To(request, 200, order);

    // The reply goes to operation.ResponseTopic, with hermod-correlation-id copied from the request. On Kafka copy hermod-reply-id too,
    // and use it as the message key: Archr.Hermod finds its waiting caller by it.
    publish(operation.ResponseTopic, reply.ToBytes(), new Dictionary<string, string> { [PapinetHeaders.CorrelationId] = request.CorrelationId });
}

TypeScript

TypeScript
/** What the adapter does for you, if you would rather read the queue yourself: read the request, answer it, and publish the reply where the request said. */
export async function answerWithoutTheAdapter(payload: Uint8Array, headers: { [name: string]: string },
    publish: (topic: string, key: string, value: Uint8Array, headers: { [name: string]: string }) => Promise<void>): Promise<void> {
    // A message arrived on papinet.v4-0-0.get-supplier-orders-supplierOrderId.request
    const request = parsePapinetRequest(payload);
    const orderId = request.pathParameters["supplierOrderId"];
    const appId = request.caller.attributes["AppId"];

    const order = { id: orderId, appId } as unknown as SupplierOrderById;   // fill it in from your system
    const reply = papinetReplyTo(request, 200, order);

    // The reply goes to the topic named by hermod-reply-to, with hermod-correlation-id copied from the request. On Kafka copy hermod-reply-id too,
    // and use it as the message key: Archr.Hermod finds its waiting caller by it.
    const replyId = headers["hermod-reply-id"];
    await publish(headers["hermod-reply-to"], replyId, serializePapinetReply(reply), { "hermod-correlation-id": request.correlationId, "hermod-reply-id": replyId });
}

Python

Python
def answer_without_the_adapter(payload: bytes, headers: t.Mapping[str, str], publish: t.Callable[[str, str, bytes, t.Mapping[str, str]], None]) -> None:
    """What the adapter does for you, if you would rather read the queue yourself: read the request, answer it, and publish the reply where the request said."""
    # A message arrived on papinet.v4-0-0.get-supplier-orders-supplierOrderId.request
    request = parse_request(payload)
    order_id = request["pathParameters"]["supplierOrderId"]
    app_id = request["caller"].get("attributes", {}).get("AppId")

    order = {"id": order_id, "appId": app_id}                  # fill it in from your system
    reply = reply_to(request, 200, order)

    # The reply goes to the topic named by hermod-reply-to, with hermod-correlation-id copied from the request. On Kafka copy hermod-reply-id too,
    # and use it as the message key: Archr.Hermod finds its waiting caller by it.
    reply_id = headers["hermod-reply-id"]
    publish(headers["hermod-reply-to"], reply_id, serialize_reply(reply), {"hermod-correlation-id": request["correlationId"], "hermod-reply-id": reply_id})

In Java the same is PapinetRequest.read(bytes) and PapinetReply.to(request, status, body).toBytes().

When a caller gets an error

The caller getsLook at
504Nobody answered before the deadline. Is the adapter running and connected (its status and log)? Does the operation have a handler? Is the handler slower than the deadline? Is another environment's copy using your group id?
502Your handler threw (your log has the exception), answered a status the document does not declare, or answered a body that does not match the papiNet schema: Archr.Hermod's log names the property.
400Archr.Hermod checked the request against papiNet and refused it. It never reached your back end.
404The operation or version is switched off or does not exist, or your handler answered "not found".
Nothing reaches the handlerThe topic does not exist or your account may not read it; another running copy with the same group id took the request; or the adapter's log shows it cannot reach the broker.

Next: calling trading partners from your application.

← Back to the technical reference