REST Web Services

REST enables communication with the physical MDM service request controller using HTTP operations.

REST stands for Representational State Transfer, a methodology in which each unique URL is a representation of an object. You can access and manipulate the object using HTTP operations: GET to retrieve it, DELETE to delete it, POST to create it, or PUT to update it. REST is becoming more popular across many types of businesses because of its strong advantages:
  • Exposes directory structure-like URIs
  • Transfers XML, JSON, or both
  • Gives client applications the ability to request a specific content type that is best suited for the purpose (using built-in HTTP Accept header, MIME types)
  • Is stateless
  • Uses HTTP methods explicitly (POST, GET, PUT, DELETE, etc)
  • REST is considerably simpler to use than SOAP and WSDL-based interface designs.
With the current release, the MDM REST implementation supports:
  • PUT requests of both XML, JSON payloads and XML, JSON responses.
  • XML MIME type allows you to transfer the same XML payloads that you can transfer with the RMI protocol.
  • JSON MIME type allows you to transfer the JSON payloads. The current release supports both XML and JSON. The valid types for the header are application/xml, text/xml or application/json.
  • ASI for both requests and responses. You can leverage service tailoring to simplify the requests and responses.
  • Access to all physical MDM transactions, including Physical, Administrative, and Composite transactions. For more information about the transactions, see the link to the transaction reference documentation at the end of this topic.
  • Security using the ServiceProvider and ServiceConsumer roles. By default, the MDM REST implementation uses Java Authentication and Authorization Service (JAAS). The JAAS provider is configured by the WebSphere Application Server application security policy. To alter the default, work with your WebSphere administrator.
  • Security using HTTPS/SSL.
The HTTP PUT method communicates to the MDM RESTful web services bundle within the MDM EBA.

The URI for the REST web service is http://server:port/com.ibm.mdm.server.ws.restful/resources/MDMWSRESTful

Authentication

Authentication is provided through the Authorization HTTP header. By default, WebSphere® Application Server is configured with basic authentication. Consider configuring a more secure authentication mechanism.
Recommendation: Configure WebSphere Application Server to use token-based authentication. The token-based authentication mechanism automatically overrides the default HTTP basic authentication. See the WebSphere Application Server documentation for information about configuring JWT token authentication using Trusted Association Inceptor (TAI).

Headers

The MDMWSRESTful service accepts the following headers:
Accept header
The format the client prefers to be returned
Content-Type header
The format in which the client is passing data
The current release supports both XML and JSON. The valid types for the header are:
  • XML: application/xml or text/xml
  • JSON: application/json
The following custom HTTP headers are used for MDM context:
  • TargetApplication
  • RequestType
  • OperationType
  • ResponseType
  • Parser
  • Constructor
  • CompositeTxn
  • CompositeParser
  • CompositeConstructor
  • ASI_Request
  • ASI_Response
For details about the specific applicability of the Request/Response framework context properties, see the link to the DWLServiceController documentation at the end of this topic.

Handling JSON requests/responses

The default MDM JSON model is based on the core XML schema model (MDMCommon.xsd and MDMDomains.xsd). Internally, MDM validates JSON by using these schemas.

Mapped notation api is used to build JSON. The features of this implementation are as follows:
  • XML elements that contain nested elements are mapped to JSON objects.

    <TCRMPersonBObj> is mapped to "TCRMPersonBObj": { … }.

  • XML element values are mapped to a JSON name or value pair.

    <GivenNameOne>Jane</GivenNameOne> is mapped to"GivenNameOne": "Jane"

  • XML element attributes become JSON name or value pairs within the JSON object.

    <tcrmParam name="PartyId">1</tcrmParam> is mapped to "tcrmParam": { "@name": "PartyId", "$": "1" }

    @ is prefixed to attribute. The xml element value is mapped to the name or value pair by using the name “$”. Characters, @, and $ are used to distinguish the attribute value from the element’s value.

  • An XML document that contains multiple nested elements of the same name (XML array elements) is automatically mapped to a JSON array.

    <TCRMPersonNameBObj> <PersonNameIdPK>822844191261056191</PersonNameIdPK> <NameUsageType>1</NameUsageType> ... </TCRMPersonNameBObj> <TCRMPersonNameBObj> <PersonNameIdPK>821544198626606646</PersonNameIdPK> <NameUsageType>2</NameUsageType> ... </TCRMPersonNameBObj> is mapped to "TCRMPersonNameBObj": [ { "PersonNameIdPK": "822844191261056191", "NameUsageType": "1", ... }, { "PersonNameIdPK": "821544198626606646", "NameUsageType": "2", ... }] )

Note: In some instances, you need to force the return of a JSON array. It occurs in the case of list type elements in MDM or results that include multiple elements.

To control this behavior, you can set the elements that need to be forced as JSON array by using the configuration management element, /IBM/DWLCommonServices/Restful/JsonResponse/ArrayObjects (comma-separated value list).