The REST Interface

Spectrum OnDemand provides a REST interface to web services. The interface supports the GET and POST methods. User-defined web services created in Spectrum Enterprise Designer support GET and POST methods. Default services installed as part of a module only support GET. If you want to access one of these services using POST you must create a user-defined service in Spectrum Enterprise Designer.

To view the REST web services available on your Spectrum OnDemand server, go to:

http://server:port/rest

Note: It is recommended that you limit parameters to 2,048 characters due to URL length limits.

Note: For more information about HTTP status codes, see HTTP Status Codes .

Service Endpoints

The endpoint for an XML response is:

http://server:port/rest/service_name/results.xml

https://OnDemandServer/rest/service_name/results.xml

The endpoint for a JSON response is:

http://server:port/rest/service_name/results.json

https://OnDemandServer/rest/service_name/results.json

Endpoints for user-defined web services can be modified in Spectrum Enterprise Designer to use a different URL.

Note: By default Spectrum OnDemand uses port 8080 for HTTP communication. Your administrator may have configured a different port.

For a list of Spectrum OnDemand servers, see Connecting to Spectrum OnDemand Servers.

WADL URL

The WADL for a Spectrum OnDemand web service is:

http://server:port/rest/service_name?_wadl

https://OnDemandServer/rest/service_name?_wadl

For a list of Spectrum OnDemand servers, see Connecting to Spectrum OnDemand Servers.

For example:

http://myserver:8080/rest/ValidateAddress?_wadl

https://spectrum.precisely.com/rest/ValidateAddress?_wadl

Note: We may add new fields or options at any time without notice. New elements are always optional so you will not have to modify your code to accommodate them unless you want to use them. If we delete fields or options we will communicate the changes to you in advance so that you have time to update your code.

Important: Do not validate web service responses against the WADL. Spectrum OnDemand WADLs are designed to be extended over time, so all elements in the WSDL are optional. This means that validating a response against the WADL produces no useful results.

User Fields

You can pass extra fields through the web service even if the web service does not use the fields. These fields are returned, unmodified, in the user_fields section of the response. For GET requests, user fields are passed in as a parameter in the URL like any other field. For POST requests, user fields are passed in as part of the user_fields element in the XML or JSON request.

Note: User field names may not contain characters that are invalid in XML or JSON element names. For example, spaces are not valid.

Sample REST Request Using GET with XML Response

The following example illustrates how to make a REST request to the ValidateAddress service using the GET method requesting a response in XML.

http://myserver:8080/rest/ValidateAddress/results.xml?Option.OutputCasing=U&Data.AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759

https://spectrum.precisely.com/rest/ValidateAddress/results.xml?Option.OutputCasing=U&Data.AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759

The sample request would result in this response since an XML response was requested:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml.ValidateAddressResponse xmlns="http://www.precisely.com/spectrum/services/ValidateAddress">
    <output_port>
        <Address>
            <Confidence>82</Confidence>
            <RecordType>Normal</RecordType>
            <CountryLevel>A</CountryLevel>
            <ProcessedBy>USA</ProcessedBy>
            <MatchScore>0</MatchScore>
            <AddressLine1>1825 KRAMER LN</AddressLine1>
            <City>AUSTIN</City>
            <StateProvince>TX</StateProvince>
            <PostalCode>78758-4260</PostalCode>
            <PostalCode.Base>78758</PostalCode.Base>
            <PostalCode.AddOn>4260</PostalCode.AddOn>
            <Country>UNITED STATES OF AMERICA</Country>
            <user_fields/>
        </Address>
    </output_port>
</xml.ValidateAddressResponse>

Sample REST Request Using GET with JSON Response

The following example illustrates how to make a REST request to the ValidateAddress service using the GET method requesting a response in JSON.

http://myserver:8080/rest/ValidateAddress/results.json?Option.OutputCasing=U&Data.
AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759

https://spectrum.precisely.com/rest/ValidateAddress/results.json?
Option.OutputCasing=U&Data.AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759

The sample request wold result in this response since a JSON response was requested:

{
	"ns1.json.ValidateAddressResponse" :
	{
	"ns1.output_port" :
	{
	"ns1.Confidence" : 82,
	"ns1.RecordType" : "Normal",
	"ns1.CountryLevel" : "A",
	"ns1.ProcessedBy" : "USA",
	"ns1.MatchScore" : 0,
	"ns1.AddressLine1" : "1825 KRAMER LN",
	"ns1.City" : "AUSTIN",
	"ns1.StateProvince" : "TX",
	"ns1.PostalCode" : "78758-4260",
	"ns1.PostalCode.Base" : 78758,
	"ns1.PostalCode.AddOn" : 4260,
	"ns1.Country" : "UNITED STATES OF AMERICA"
	}
	}
}