Spectrum Technology Platform Version 2018.2.0
Total Page:16
File Type:pdf, Size:1020Kb
Spectrum Technology Platform Version 2018.2.0 Web Services Guide Table of Contents 1 - Getting Started REST 4 SOAP 26 2 - Web Services Enabling CORS 46 REST 47 SOAP 463 Chapter : Appendix Appendix A: Buffering 871 Appendix B: Country Codes 874 Appendix C: Validate Address Confidence Algorithm 899 1 - Getting Started In this section REST 4 SOAP 26 Getting Started REST The REST Interface Spectrum™ Technology Platform provides a REST interface to web services. User-defined web services, which are those created in 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 Enterprise Designer. To view the REST web services available on your Spectrum™ Technology Platform server, go to: http://server:port/rest Note: We recommend that you limit parameters to 2,048 characters due to URL length limits. Service Endpoints The endpoint for an XML response is: http://server:port/rest/service_name/results.xml The endpoint for a JSON response is: http://server:port/rest/service_name/results.json Endpoints for user-defined web services can be modified in Enterprise Designer to use a different URL. Note: By default Spectrum™ Technology Platform uses port 8080 for HTTP communication. Your administrator may have configured a different port. WADL URL The WADL for a Spectrum™ Technology Platform web service is: http://server:port/rest/service_name?_wadl For example: http://myserver:8080/rest/ValidateAddress?_wadl 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 Spectrum Technology Platform 2018.2.0 Web Services Guide 4 Getting Started 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 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.pb.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 The sample request wold result in this response since a JSON response was requested: { "ns1.json.ValidateAddressResponse" : Spectrum Technology Platform 2018.2.0 Web Services Guide 5 Getting Started { "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" } } } JSON POST Request User-defined web services can be exposed as a REST web service and configured to have a POST method that accepts JSON input. Specify Content-Type:application/json and use the following format for JSON POST requests. Flat Data Use this format in the body request to send flat data to a web service using POST. { "InputStageName": { "InputDataType": [ { "FieldName1": "FieldValue1", "FieldName2": "FieldValue2" } ] } } Where: InputStageName The name of the input stage as shown on the canvas in Enterprise Designer. The default name of the stage is Input. InputDataType The name given to the record-level entity. This value is specified in the dataflow's Input stage, in the Data type name field on the Input Fields tab. The default name of the record-level entity is Row. Spectrum Technology Platform 2018.2.0 Web Services Guide 6 Getting Started FieldName1 and FieldName2 The names of the input fields defined in the service's Input stage. FieldValue1 and FieldValue2 Input data that you want to send to the web service in the corresponding field. List Data List data consists of hierarchical groupings of fields grouped under a parent field. Note: In order to use list data as input, the service must be exposed as a REST web service without any GET resources. If the service has a GET resource you will get an error in Enterprise Designer when exposing the service because hierarchical fields are not supported for GET. Use the following format to send list data to a web service using POST. { "InputStageName": { "InputDataType": [ { "ListField1":[ {"SubfieldName1": "SubfieldValue1"}, {"SubfieldName2": "SubfieldValue2"} ] } ] } } Where: InputStageName The name of the input stage as shown on the canvas in Enterprise Designer. The default name of the stage is Input. InputDataType The name given to the record-level entity. This value is specified in the dataflow's Input stage, in the Data type name field on the Input Fields tab. The default name of the record-level entity is Row. ListField1 The name of the hierarchical field defined in the service's Input stage. SubfieldName1 and SubfieldName2 The names of child fields that comprise the list field. SubfieldValue1 and SubfieldValue2 Input data that you want to send to the web service. Spectrum Technology Platform 2018.2.0 Web Services Guide 7 Getting Started User Fields You can pass extra fields through the web service even if the web service does not use them. These fields are returned, unmodified, in the user_fields section of the response. The user fields you supply in the request do not need to be defined in the service dataflow's Input stage. { "InputStageName": { "InputDataType": [ { "user_fields": [ { "name": "FieldName1", "value": "FieldValue1" }, { "name": "FieldName2", "value": "FieldValue2" }] } ] } } Where: InputStageName The name of the input stage as shown on the canvas in Enterprise Designer. The default name of the stage is Input. InputDataType The name given to the record-level entity. This value is specified in the dataflow's Input stage, in the Data type name field on the Input Fields tab. The default name of the record-level entity is Row. FieldName1 and FieldName2 The name of the pass-through field. FieldValue1 and FieldValue2 The data you want to include in the passthrough field. Options You can specify options in the request, overriding the default options specified in the service dataflow. For user-defined web services, you can only specify options in the request if the dataflow has been configured to accept options. To configure a service to accept options in the request, open the service in Enterprise Designer and select Edit > Dataflow Options. Spectrum Technology Platform 2018.2.0 Web Services Guide 8 Getting Started To specify processing options in a request, use this format: "options" : { "OptionName1" : "Value1" }, Where: OptionName1 The name of the option. For a list of valid options for the service see the service's WADL or open the service in Enterprise Designer and select Edit > Dataflow Options. OptionValue1 A legal value for the option. For a list of legal values, open the service in Enterprise Designer and select Edit > Dataflow Options. Example JSON Request using POST The following example demonstrates how to include options, flat fields, a list field, and user-defined fields in a JSON request to a web service using POST. { "options" : { "OutputCasing" : "U" }, "Input": { "Address": [ { "AddressLine1": "1825 Kramer Ln", "City": "Austin", "StateProvince": "TX", "Accounts": [ { "AccountNumber": "120993", "ExpirationDate": "10-3-2017" }, { "AccountNumber": "898732", "ExpirationDate": "8-13-2016" } ], "user_fields": [ { "name": "Note1", "value": "Prefers decaffeinated coffee" }, { "name": "Note2", "value": "Requests east facing window" Spectrum Technology Platform 2018.2.0 Web Services Guide 9 Getting Started }] } ] } } In this example, • OutputCasing is an option exposed by the web service that controls whether the output is returned in upper case or lower case. In this request, it is set to U for upper case. • Input is the label of the Input stage in the dataflow as displayed on the canvas in Enterprise Designer. • Address is the name of the record-level entity as specified in the dataflow's Input stage, in the Data type name field on the Input Fields tab. • AddressLine1, City, and StateProvince are flat fields. • Accounts is a hierarchical ("list") field containing subfields