API Requests and Responses

URI Structure

Many of Radial's APIs follow this structure for URIs:

https://env-rr.gsipartners.com/vM.m/stores/STOREID/service/operation[/parameters].format

URI elements in bold font above are described in more detail below. Only representative parameters are shown. Any additional text is required “as is” within the URI structure. Square brackets ([ ]) in the URI above indicate optional elements. Refer to the individual service operation for details on usage.

For production API access for North American customers, Radial recommends the domain name https://apg.radial.com. (The old domain name, https://api-na.gsipartners.com, will continue to work until further notice.)

For test environments and customers outside North America, the domain name for API access is based on the formula https://env-rr.gsipartners.com, as follows:

• env – The Radial environment that is being accessed by the client application. Different environments are provided to support the various SDLC stages of the application. Only environments that the client application has been granted access to are available. Radial environments include:
  • developer – the environment provided for functional testing and user-acceptance testing.
  • api – the Radial production environment
  • beta – used by “early adopter” clients who are participating in beta testing of functionality that has not yet been release to the Radial production environments.
• rr – The geographic region that has been assigned to the e-commerce application by Radial. Applications are assigned a geographic region which corresponds to a data center and allows Radial to optimize API response times for the client applications. Only geographic regions that the client application has been granted access to will be available. Radial geographic regions include:
  • na (North America)
  • eu (Europe)
  • ap (Asia-Pacific)

URI elements after the domain name include the following:

• M.m – The major (M) and minor (m) version numbers of the API being accessed by the client application. . The letter v is a literal value that precedes the major and minor version numbers in the URI.
• STOREID – The Radial store identifier assigned to the e-commerce application calling the API. This identifier must appear in the URI in ALL CAPITAL letters.
• service – The service or subject area of the EP API represented in the URI.
• operation[/parameters] – The portion of the URI that describes the specific operation of the service being called. Some operations require additional resource parameters (these are specified in the individual service operation details). These are indicated with a “/”, then the parameter name.
• .format – The file extension format for the response of the requested service operation. The only current supported response format is .xml. This format extension value is required in all service calls.

Making Requests

You can manually create a request and send it to the web service layer using the Firefox REST client, Google Chrome REST client, or another REST client.

• Make your request to the correct URI for the service.
• Pass the parameter apikey as a header argument.
• Send the request using a POST action.

Responses

After a request is sent to the web service layer, one of the following scenarios occurs:

• A connection is established and a valid response is received from the web service.
• An explicit connection error occurs when contacting the web service layer.
• A timeout occurs when receiving the response from the web service layer. (This should occur only if the client timeout values are set below the recommended timeout values.)

A valid response from the web service layer can take any of the following forms:

• The requested response XML message
• A simple acknowledgment XML message (such as in the case of an order create request)
• A fault response XML message, if there was an error in processing the request

Fault Responses

Radial APIs use a common fault response schema to provide consistency across the service calls. The Checkout-Service-Fault-1.0.xsd element documents the response that is returned for any call that cannot be serviced properly by the Radial platform. This is a top-level element.

A fault will be returned any time an exception occurs that prevents a transaction from being processed properly, including:

• Invalid input that violates the service interface.
• General system errors.
• Attempting to access operations not available to this client.
• Attempting to access environments not available to this client.
• A required downstream service not being available (internal timeout).
• XML validation failure.

Response Header

During the use of Radial APIs, the consumer of the service sends a request to the service and receive a response from the service. The response contains a response header and a response body, in the same way that the request contained a request header and request body.

The response header contains the following data elements:

When an error occurs during the processing of a request, the response header will contain an error HTTP status code and the response body content will contain the details of the cause of the error.

Error Status Codes

400 Series Status Codes

400 series error status codes indicate a problem with the API request. These problems can include the following:

• 400 – The request can not be validated as it does not match the required schema.
• 401 – The request could not be authorized to access the requested service with the API key provided.
• 403 – The request attempted to access an unauthorized or incorrect version of the API, client channel, store code or URI.
• 405 – The service request made may have used an insecure HTTP protocol instead of the SSL protected “HTTPS” protocol. This status code may also be returned if an HTTP method other than POST is used when making the service request.

These requests must be corrected before attempting to resubmit them. Without first correcting the problem specified in the response, the request will never be successfully processed.

500 Series Status Codes

500 Series Errors indicate a problem with the systems processing the request. These problems can include the following:

• Incorrect Service Call URI – A 500 error will be returned if a URI that does not correspond to an actual service is called.
• Request Parse Error – The request could not be parsed by the receiving service. This may be due to schema validation failure.

These requests must be evaluated to determine if any changes are needed before they can be resubmitted.

Error Response Message Example

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <CreateTimestamp>##TIME_STAMP##</CreateTimestamp> 
  <Code>##CODE##</Code>
  <Description>##DESCRIPTION##</Description>
</Fault>