The Hornbill API provides a comprehensive access to the functionality of Hornbill’s Platform and Applications.

The Hornbill API falls into the general category of a Web Service API, that is, it’s based on standards and protocols commonly used on the internet for communications between different computer systems. The Hornbill API can be further described as an API that uses JSON or XML formatted messages sent as a request payload, using HTTP as a payload transport, and, just like the content of the World Wide Web, we use those same standard industry-strength transport and security protocols.

The Hornbill API function can be thought of as an Remote Procedure Call (RPC) style API, a model used widely and extensively in distributed computing systems. When you make an API call to the Hornbill service, you are sending a message requesting some form of action, or asking for some specific data or information. The Hornbill service will verify security, act on that request, and produce a response message, returning the resultant message to you in the HTTP response.

The Hornbill API is similar to a ReSTful (Representational State Transfer) API, meaning that the API uses HTTP methods such as GET, POST, PUT, and DELETE to perform operations on the API messages. For example, a client application might use a GET request to retrieve JSON data from a server, or a POST request to send JSON or XML message to a server for processing.

![Encapsulated message in HTTP Image goes here…]

HTTP is a standard protocol used initially for communication over the internet between web browsers and web servers. Over the years the protocol has been extended to also provide a unified way for systems to exchange data in a well-defined and consistent manner too. By using HTTP to exchange the Hornbill API messages, the use of HTTP over both intranet and internet systems based on TCP/IP, provides a way for applications and systems to communicate with each other, regardless of the programming language or platform being used. HTTP is ubiquitous and supported by everything from mainframes right down to nano IoT systems.

Major advantages of HTTP is its stateless, wide support for it on almost every platform, and there are well defined, time-proven, mature and robust security protocols available, ensuring the Hornbill API has the highest levels of security at all times, while enabling security researchers and teams to analyze and understand the security model and technical architecture for validation of compliance against their own standards.

JSON or XML

The Hornbill API was originally designed as far back as 1998 and has been in production use since around the year 2000. The original implementation only used XML for messages, and for definition and message validation XML Schema was adopted as a well-defined, flexible schema descriptor language. UTF-8 was chosen as the only supported character encoding scheme, and HTTP was chosen as the network transport. These technology choices are still the foundation of the Hornbill API today. However, as time progressed and technology and the internet evolved, most business applications have migrated over to browser-based applications running in the cloud. While XML and XML Schema remain a powerful and very extensible technology choice, modern web browsers offer poor to almost no support at all for XML. Instead, primarily because of the ubiquitous use of JavaScript as the web programming language of choice, JSON emerged as the de-facto standard for data representation in web applications, where good native support has evolved along with the browser technologies.

The Hornbill API has evolved at the same time, firstly by supporting JSON transformation of XML response messages, followed by native JSON request message handling and input validation. This was achieved by defining a sub-set of XML and XML Schema specification that maps perfectly over to JSON data representation. In practical terms this means that now you can use either XML or JSON for API calls to Hornbill.

Most of our API traffic today is serving web browser originated requests, so over time we have prioritized the optimization of the API processing for JSON messages over XML messages (although both are still very fast), so we recommend using JSON instead of XML, unless you have a very good reason to do otherwise. It is possible that over time we may start to deprecate our use of the XML messaging format, simply because JSON is a better choice for modern web-based systems and technical architectures.

The API Reference documentation will show all examples in both JSON and XML format.

There is also a more comprehensive explanation in the article Unified JSON and XML Message Format covering the details of how XML and JSON are supported, and what standard approaches we have applied to the XML format we use in order to ensure 100% compatibility with JSON representation, as well as how we continue to make use of XML Schema to provide comprehensive, high quality input message validation for both XML and JSON messages.

API Services

The Hornbill platform and its applications present a large number of APIs, most likely more than you will ever (want) to see or use. The Hornbill Platform is made up of a number of well-defined “services” where each service typically provides functionality specific to one specific area of the platform or application. Hornbill APIs are organized into groups also known as API Services, and there is a one-to-one correlation between the Platform Services and the API Services.

API Endpoint

Each Hornbill instance has a unique API endpoint, which is made up of the following elements:

https://{dc}-{pod}.api.hornbill.com/{instanceId}/xmlmc

All API calls related to your instance must go to this specific endpoint. The datacenter {dc} is located in the same region as your data and compute services where your instance is physically hosted.

In order to locate your instance’s API endpoint, you can log into your instance and navigate to Configuration -> Hornbill Solution Center -> Your Usage -> Support where your instance-specific endpoint will be shown here: -

Protocol Support

Hornbill API endpoints only use HTTPS as the transport scheme for API calls. The Hornbill API endpoint servers support HTTP over secure sockets only, so any requests need to first establish a secure connection using TLS and a strong encryption scheme. Fortunately on almost all systems this complex process happens in the background so you don’t need to know anything other than the endpoint must always start with https://. The Hornbill API works with any generation of HTTP so long as the connection is secure. Any of HTTP/1.0, HTTP/1.2 and HTTP/2.0 as well as other supported HTTP extensions such as persistent/reusable connections, message pipelining are all supported.

Data Polling, Extraction or Importing

Unless explicitly stated for any specific available API, our API’s are designed for transactional purposes and/or data querying that is commensurate with typical user interactions through our user interface or for point integrations that require transactional interactions. Specifically, the API’s are optimized for this transactional purpose, and should only be usd in this context. Polling for data state changes, or using API’s to periodically extract data out of the system for other processing, reporting, dashboards while may be technically possible, is not advised, if unacceptable use patterns are detected your API’s will most likely be rate limited, or even suspended for periods of time.

Please see our Data Polling Policy for further information