REST Response Output Formats

You can explicitly specify the format of the data returned by the REST service at the end of the path information, as shown in the following examples.

• /customer/123.xml returns customer information in Microsoft XML format.

  The XML format is as expected by the Microsoft DataContractSerializer class for an Object or a TimeStampInterval primitive return value. While other primitives return values are formatted for the Microsoft XmlSerializer, XmlSerializer does not support the TimeSpan type. The output includes identifiers for each object included and references to already included objects, which enables the returned data to contain circular references and multiple references to the same object.

  The XML returned for an object lists the properties in alphabetical order within each class of the hierarchy, working from the highest superclass down through each subclass.

• /customer/123.json returns customer information in Microsoft JSON format.

  The JSON format is as expected by the Microsoft DataContractJsonSerializer class. This format type does not support circular references or multiple references to the same object in the returned data. An exception is raised if a circular reference or multiple references to the same object are detected. This format is the default if no format was specified.

• /customer/123.jsonn returns customer information in NewtonSoft JSON (JSONN) format.

  The JSONN format is as expected by the NewtonSoft JSON class software. It differs from Microsoft in the structure, tags, and the format of some primitive types. The output includes identifiers for each object and references to already included objects, which enables the returned data to contain circular references and multiple references to the same object.

If the output is not explicitly specified at the end of the path information (as described in the previous examples), the REST application attempts to deduce the required output from the REST request header.

REST requests can contain an Accept header field. The Accept header field is used by the client to signal to the REST server which content types it can process. The following are examples of Accept header fields that could be used when sending requests.

Accept: */*

Accept: image/png

Accept: application/json

Accept: application/xml

Accept: application/json, application/xml

If the Accept header field:

• Contains application/json, the REST service returns the customer information in Microsoft JSON format.

• Contains application/xml, the REST service returns the customer information in Microsoft XML format.

• Contains application/xml and application/json, the REST service returns the customer information in Microsoft JSON format.

• Is absent or contains */*, the REST service deduces the output format using the Content‑Type header field (using the logic that it will try to match the format of the response to the format of the request payload).

REST requests with payloads should contain a Content‑Type header field. The Content‑Type header field is used by the client to tell the REST server the format of the request payload. The following are examples of Content‑Type header fields that could be used when sending requests.

Content-Type: application/xml

Content-Type: application/json

Content-Type: text/html; charset=utf-8

Content-Type: multipart/form-data; boundary=ExampleBoundaryString

If the Content‑Type header field:

• Contains application/xml, the REST service returns the customer information in Microsoft XML format.

• Contains application/json, the REST service returns the customer information in Microsoft JSON format.

• Is absent or contains neither application/xml nor application/json, the REST service returns the customer information in Microsoft JSON format by default.