API Business Objects

Strong business objects are the key advantage of powerful APIs.

August 13, 2019 | 2 Min.

Author: dataliquid GmbH

Powerful APIs are characterized by a wide range of functions. In addition to the functions, the technical data is the most important factor for acceptance by API consumers. Business objects define the technical data structures which can be exchanged between the respective API function and the consumer. API resources (function of an API) distinguish between business objects for the request and for the response.

All business objects used in an API are described and managed in the API Definition. The business objects can be reused within an API. As an example, we will take an Order API, with which new orders can be created and the order status can be retrieved. If an order is created via the API, the data structure of the order type must be transferred to the API. The data fields and data types are defined in the data structure. The data type specifies the type of the data field, for example, numbers, character strings, or lists.

An OrderType consists of the following information:

  • Order number

  • Customer number

  • Order date

  • Order items

  • Order status

The common API specifications support almost all data types. The following simple data types are the most commonly used:

  • string

  • number (decimal number)

  • integer

  • boolean (truth values true, false)

  • array (list of values)

  • date

The data types are now defined for the data fields mentioned above in our example. An order number can consist of characters and numbers, so we define string. The customer number consists only of numbers and is therefore number. The order date is declared as date-only according to the international date and time format ISO 8601. The order items are an array, since several items can be contained in an order, which are defined as independent business objects.

In addition, further facets of a data field can be declared. The more comprehensively an API is defined, the more stable and resilient an API is. The minimum and maximum length of a data field of type string can be defined by facets. For example, the field may contain a minimum of 2 characters and a maximum of 20 characters. If the data field Price of type number is described, the minimum value and maximum value as well as the decimal places can be defined. As an example, the price must be at least 0.00 and at most 5,000 of a currency unit. Two decimal places are allowed. The example values NEW, SHIPPED, DELIVERED and CANCELED can be specified for the order status data field, making it much easier for the user to understand the data field and its use.

For each data field a technical example value can be given, this creates a substantial increase in value for the user, since the understanding and usability of the API is practically clarified.

By a strong characteristic of the business objects the API achieves a high transparency. This makes it easy for interested parties and developers to understand and use the interfaces and the underlying business processes.