API Best Practices

Validate Request Against XSD

Before calling any Radial API, validate the request against the XSD for the request message. Validation helps catch XML errors as early in the process as possible, which speeds up locating and resolving errors related to malformed XML. It also reduces the number of service failure responses returned to the client web store.

Use Unique Request ID

Many of the service calls are idempotent and must have a unique request ID. If you make a subsequent service call with the same request ID, the response will generally reflect the original call made with the same request ID, dependent on the nature and extent of the data changes within the request.

Use CatalogID as a Prefix to ItemID

Use your store's Radial-assigned CatalogID as a prefix to your ItemID value. Any service request that requires an itemID field should use CatalogID-CLIENTITEMID. The hyphen (-) is required.

Log Requests and Responses

It is a recommended best practice to add a logging appender to create a log that records API requests and responses. Radial recommends that you implement this logging at the start of development. To prevent this log from becoming too large in production, make logging statements that write to this log a low enough logging level that they do not happen in production, similar to a logging level such as “debug” or “info.”

Design Tests for Future Compatibility

While Radial will make changes and enhancements to product capabilities in the future, there are steps that client developers can take to retain compatibility with future versions of APIs as much as possible, depending on the enhancement of functionality.

Radial real-time service schemas include xsd:any elements to help client code leave expansion room for future functionality. Within each schema, this element indicates that future optional elements may show up in this location of the XML document in the responses returned from the service. There may be cases where it is not possible to include an xsd:any element, so client developers should allow for cases where service responses may include elements not previously encountered in the published schema. These new elements will be optional and may be ignored by the client system.

The purpose of xsd:any elements is to allow for new, optional elements to be added to the service's responses without the client code experiencing exception errors. The client code for this service call should be written so that it will not break if new optional XML elements show up in this part of the service response.

Modern XML marshalling frameworks often process xsd:any elements properly out-of-the-box (for example, in Java, JAXB and JibX XML marshalling frameworks both honor xsd:any elements and don't throw exceptions if new optional elements appear within the xsd:any section of the XML document).
Developers' unit tests of their service client code should include a test case where this reply message contains one or more new elements in this location of the XML document. When new optional elements are added to this interface, a new schema will be created and communications will be sent out. If there is no need/desire to process the new optional elements, service client should continue to run uninterrupted as long as it is built to honor this xsd:any element.

Operation Response Times

When making service requests over the internet, there are multiple factors that can impact response times. When considering appropriate timeout values for requests, take these factors into account:

Timeout connecting to the service and timeout of the response delivery. As with any internet delivery, these durations depend on internet service providers, internet node traffic or availability, distance that packets need to travel and package routing paths, and similar factors.
Timeout of downstream dependencies that the service uses to complete its operations. The Radial service must communicate with downstream systems to complete its operations, such as the bank in the case of a payment authorization. These downstream systems often require their own service calls, which are made from the Radial service.
Timeout of the Radial service itself. The service depends on the previous items in this list, but timeouts could also indicate an issue with the service.

Response times for Radial service calls typically complete in under 5 seconds. Due to the nature of service requests made over the internet and the dependency of third party systems, each subject area of the Radial web service layer defines its own timeout values for receiving responses from downstream systems.

Retail Order Management Service Identifier	Upper-bound Response Time (milliseconds)
address	5000
inventory	30000
taxes	20000
payments	70000
orders	30000

These times are worst-case scenario values. They represent the most extreme case when responding to a web service request, and these cases occur for less than one percent of all web service calls. Currently, the largest outlier response times for any Radial web service response times do not exceed 30 seconds.

Be certain to consider all of these factors when determining what timeouts work best for your platform based on the expected response times and the platform’s topography.