Skip to content

Custom Rules

The Connect API interface avoids exposing implementation internals, so it can be implemented by multiple applications. The approach is for each implementation to handle their own business rules and act appropriately depending on their business needs.

Sometimes, actions taken by a client through the API might conflict with the configured behavior of the application. To avoid conflicts, the API can support an optional rules property that can specify application specific behavior. The rules property is a JSON object which schema and structure becomes a contract between a client and a specific implementation.

This document explains:

  • The type of problems the rules property solves.
  • The basic structure of the rules property.
  • The recommended approach for implementers.
  • The considerations clients should take into account.

Problem Basics

Applications that expose the Connect API interface want to maintain the integrity of their data. At the same time, clients want to use the API consistently without knowledge of the underlying implementing application. This can create conflicts between the application business rules and the rules the client wants to enforce. As an example, we will use Order Automation and one of the issues found when creating orders in Profit Tools.

Profit Tools customers can configure the application to auto-rate shipments based on some properties of the shipment. These customers might also use Order Automation to create new orders.

The specification received by Order Automation might already contain rates for the items added to the shipment, so Order Automation will create those items. Profit Tools will then auto-rate the shipment, and the auto-generated rates might conflict with what Order Automation has created.

The side effects of this can range from invalid rate to duplicate rates. In either case, the result is unwanted.

Ideally, Order Automation should notify Profit Tools that it is going to add the rates and that no auto-rating should be performed by the application. Unfortunately, this behavior is specific of Profit Tools and other implementations will not have this problem. The solution should not be enforced by the Connect API interface. Instead, it should be an optional contract between the client and the application that can be ignored by applications that do not support the functionality.

Introducing Rules

The client can notify the application of its intention by passing information in a rules object. The receiving application can then choose to support the rule or ignore it if it violates its data integrity.

In the case exposed above, Order Automation can pass a rule that disables the auto-rating feature when a shipment is created:

POST /shipments

The following example shows the rule and removes additional payload properties to create a shipment:

{
  // Payload to create a shipment
  "rules": {
    "autoRate" false
  }
}

The autoRate rule is a contract between the client and the handling application to skip auto-rating when the propery is set to false.

An application like Profit Tools can choose to support the rule and disable auto-rating, where other applications might choose to ignore the rule and still auto-rate the shipment or maybe do nothting because they don't support auto-rating altogether.

Implementing Rules

Applications that decide to support rules can do so in any of the Connect API endpoints. Since rules override business behavior in the application, it only makes sense to use them when data is created (POST), updated (PUT), or deleted (DELETE). Rules should not be exposed in GET requests in the API.

The rules supported by an application should be documented, so clients can know they exist and choose use them. Rules that are not supported can be ignored, and the existing behavior should be maintained.

Rules are always exposed through a rules object at the root of the payload, and the property names for the rules should be descriptive of the behavior:

{
  // Payload in the Connect API interface
  "rules": {
    "standardRule": false
  }
}

Rule names should be reused by other applications if they intend to support the same functionality. It is important to document defined rules as to prevent duplication.

⚠️ Avoid rule names in a negative form because they can cause confusion when reading. Prefer autoRate = false to disableautoRate = true, which is harder to read.

Integration Rules

Clients that decide to leverage rules should understand that it is not a standard functionality supported by every application and that some of the applications might decide to ignore the rule even if the functionality is supported.

As an example, the application might decide to ignore the autoRate rule even when they do support an auto-rating feature, in which case the shipment will be auto-rated regardless.

A good choice for a client is to always specify the rules for the behavior they want and let the application choose whether to support the rule or not.

Conclusion

Rules allow clients to override business behavior in the supporting applications. At the end, the application must warrant data integrity, so it will decide if it can support a rule or not.

Clients should always use rules aware that the responding application might not support it and that the end result will not be what was intended. The rule is a contract between a client and a supporting application, but in no way it is required for all applications to support the rule.

Created rules should be documented and maintained so clients can leverge them. Applications should standarize rules to avoid duplication.