Technical Reference

papiNet REST API

A secured HTTPS API for your trading partners, built from the papiNet specification and carried over your message queue to the system that holds the data.

papiNet is the paper and forest-products industry's standard for supply-chain messages. Its REST API describes how a logistics supplier asks a supplier for supplier orders, delivery instructions and delivery notes, and reports goods receipts and inventory changes. Archr.Hermod serves that API for you: your trading partners call an ordinary HTTPS endpoint, and your own system never has to face the internet.

Archr.Hermod reads the papiNet document and publishes one endpoint for each operation in it. There is no endpoint code to write or keep in step with the specification. It does not interpret the business content: it authenticates, validates, carries and records, and your back-end system does the real work.

How a call is handled

  1. The operation is found from the papiNet document. The exact papiNet version is part of the address (for example /papinet/4.0.0/supplier-orders).
  2. The caller is authenticated by API key. The key belongs to a caller record that carries attributes you define, such as an application id, a business unit or the parties the caller may see. They are set by you, not by the caller, and reach your back end with the request so it knows whose data to return.
  3. The request is validated against the document's JSON Schema — path, query and body. A request that does not comply is refused with 400 and never reaches your system.
  4. A request message is published on your message queue (NATS or Kafka), on a topic named after the version and the operation, such as papinet.v4-0-0.get-supplier-orders.request, with a correlation id and a deadline.
  5. Your back end replies with a status and a body. Archr.Hermod passes through only the statuses the document declares for that operation; anything else becomes 502. Optionally, the body of a successful reply is checked against the document too.
  6. No reply before the deadline (30 seconds by default) gives the caller 504, so a caller is never left waiting.

Versions never change underneath a partner

Every papiNet version is a separate, immutable API, and several can be live at the same time. An administrator chooses which versions are live; an alias such as v4 can point at one registered version, and moves only when an administrator moves it. Because the version is in the topic name, switching a version on cannot deliver messages to a back end that does not know it.

Administration

The API is off until an administrator switches it on, and it needs a message queue. Without one it does not start.

← Back to the technical reference