About OpenAPI

OpenAPI is the most widely adopted format for describing HTTP APIs. Most API clients, code generators and testing tools can import an OpenAPI document and build a ready-to-use request collection from it.

We publish an OpenAPI description of the Hornbill Platform API alongside this documentation, generated from exactly the same API contracts that produce the reference pages in this book. It cannot drift from the documentation, because both are built from the same source in the same step.

Audience

The OpenAPI description is aimed at developers building integrations against the Hornbill Platform who would rather work from their own tooling than from the browser. It is an alternative to the Postman Examples collection, useful when your tool of choice is something other than Postman — Bruno, Insomnia, Swagger UI, or an SDK generator.

Download

Download the OpenAPI description (OpenAPI 3.0.3, JSON).

Most tools will also accept the URL directly, which saves re-downloading when the description is updated:

https://docs.hornbill.com/_books/esp-api-api/hornbill-platform-openapi.json

Before your first call — set apiBase

The description is published for every Hornbill customer, so it cannot know which instance you are on. Every request will fail until you point it at yours.

The document declares a single server variable, apiBase. To find its value:

1. Open https://files.hornbill.com/instances/<your-instance>/zoneinfo in a browser
2. Copy the apiEndpoint value, for example https://hhq-p01-api.hornbill.com/acme/xmlmc/
3. Set apiBase to that value, without the trailing slash

Where you set it depends on your client — in Swagger UI it is the Servers box at the top of the page; in Bruno, Insomnia and Postman it becomes a collection variable when the document is imported.

Authentication

The description declares two security schemes. Both are supported by the platform:

For most integration work an API key is the right choice.

How operations are addressed

Platform API operations are dispatched from the message body, not the URL — the service reads @service and @method from the payload. Because OpenAPI identifies an operation by its path and HTTP verb, the description gives each method its own path so that clients can list and call them individually. Those paths route correctly as written.

A request therefore looks like this:

{
  "@service": "session",
  "@method": "userLogon",
  "params": {
    "userId": "admin",
    "password": "<base64-encoded password>"
  }
}

The @service and @method values are fixed per operation and are pre-filled by the description, so in practice you only supply params.

The top-level methodCall wrapper required by the XML form is not needed when sending JSON.

What the description does not cover

A few things in the Hornbill API catalog have no equivalent in OpenAPI, and are omitted or relocated rather than lost:

• Privilege level, rights, lifecycle status, transactional and database role are written into each operation’s description, so they remain visible in your client. They are not machine-readable fields.
• Enum ordinal values and bit-flag weights are omitted. The string form is what you send over the wire.
• XML element ordering is not represented. It is only significant for XML payloads; the description covers the JSON form, where parameter order does not matter.
• HTTP endpoints (those served with a real verb rather than the RPC envelope) are included, with their own paths, parameters and status codes.

For the complete picture of any operation, including anything not modeled above, see the API Services reference in this book.