Previous Page Arrow Next Page Arrow

JSON responses

Provider responses to requests in (and for) JSON are in one of the following forms:

  • An entry: this is the representation of an individual resource and contains the native, JSON formatted objects
  • A feed: is a collection of entries
  • A diagnosis : returned in case something went wrong with the request
  • A tracking object: returned for an asynchronous call to enable subsequent polling of results

JSON entries

Entries encompass single resources such as a specific Customer or SalesOrder. Payloads will contain a single entry only when the request operates target an individual resource (ex: GET on a single resource URL or PUT/POST/DELETE operations).

In addition to the native properties of the resource, SData allows within an entry the presence of several protocol-defined properties meant to ease consumption. These are described in the table below:

 DescriptionCompliance
$url URL pointing to the resource.
The URL should be represented as relative to the value of the $baseUrl of the enclosing feed.

    Examples:
    given the "$baseUrl": "http://ex.com/MyApp/-/-"
  • "$url": "{$baseUrl}/customers('1234')"
  • "$url": "{$baseUrl}/customers?where=$uuid eq 'ab1C43sd-c1asdc2sT'"
If a $baseUrl property is not specified, then the URL MUST be absolute.
    Examples:
MAY
$keythe native primary key identifying the resourceMAY
$uuidUUID identifying the resourceMAY
$titlehumanly readable description of the resourceMAY
$updatedthe time stamp of the last update of the resource, formatted according to ISO 8601 dateTime specificationMAY
$etagopaque identifier assigned by the provider to a version of a resourceMAY
$properties¹Object containing metadata for the properties of the resourceMAY
$links²Object containing links that present functional aspects of the resource (ex: edit, lookup, create). They are to be understood as hypermedia controlsMAY
$diagnosisObject containing a more detailed indication of errors and warnings encountered by the provider during the execution of a requestMAY
native propertiesNative properties of the objectMAY

An example is the JSON variant of the Typical SData Entry in the SData documentation:

…
"$baseUrl": "http://www.acme.com/MyApp/-/-",
…
{ 
    "$url": "{$baseUrl}/salesOrders('43660')", 
    "$updated": "2008-03-31T13:46:45Z", 
    "$key": "43660", 
    "$title": "Sales Order 43660", 
    "$etag": "gJaGtgHyuAwW6jMI4i0njA==", 
    "orderDate": "2001-07-01", 
    "shipDate": null, 
    "contact": { 
        "$url": "contacts('216')", 
        "$key": "216" 
    }, 
    "subTotal": 1553.10 
}

JSON feeds

Feeds are collections of entries, returned by operations targeting several resources in parallel such as read or query operations on resource kinds. A feed is a JSON object with all entries contained in the $resources array - this is the only required property of a feed.

A feed may also contain a set of SData-defined properties, which are described in the table below:

 DescriptionCompliance
$resourcesArray containing the individual entriesMUST
$baseUrlURL leading to the resource kind level of an application. The URL SHOULD NOT end in a "/"
Example:
"$baseUrl": "http://www.acme.com/MyApp/MyContract/-"
MAY
$url URL pointing to the resources returned.
The URL should be represented as relative to the $baseUrl value.

    Examples:
  • "$url": "{$baseUrl}/customers"
  • "$url": "{$baseUrl}/customers?where=name ge 'm'"
If a $baseUrl property is not specified, then the URL MUST be absolute.
    Examples:
MAY
$titlehumanly readable description of the resourceMAY
$updatedthe time stamp of the last update of the resource, formatted according to ISO 8601 dateTime specificationMAY
$links³Object containing links that present functional aspects of the feed (ex: refresh, first-page, schema, template, …). They are to be understood as hypermedia controlsMAY
$diagnosisObject containing a more detailed indication of errors and warnings encountered by the provider during the execution of a requestMAY

An example is the JSON variant of the SData Typical Feed :

{ 
    "$baseUrl": "https://www.example.com/MyApp/-/-",
    "$url": "{$baseUrl}/salesOrders", 
    "$title": "Sage App | Sales Orders", 
    "$totalResults": 31465, 
    "$startIndex": 1, 
    "$itemsPerPage": 10, 
    "$resources": [
        { 
            "$updated": "2008-03-31T13:46:45Z", 
            "$key": "43660", 
            "$title": "Sales Order 43660", 
            "$etag": "gJaGtgHyuAwW6jMI4i0njA==", 
            "orderDate": "2001-07-01", 
            "shipDate": null, 
            "contact": {
                "$url": "contacts('216')", 
                "$key": "216" 
            },
            "subTotal": 1553.10 
        },
        { 
            "$updated": "2008-03-31T13:46:45Z", 
            "$key": "43661", 
            "$title": "Sales Order 43660", 
            "$etag": "3nqPeQqoGoxQB5xf3NIijw==", 
            "orderDate": "2001-07-01", 
            "shipDate": null, 
            "contact": { 
                "$url": "contacts('281')", 
                "$key": "281" 
            }, 
            "subTotal": 39422.12 
        } 
    ] 
}

JSON diagnosis

The diagnoses is an object that contains information about the status (information, warning, error) of a request’s execution. Such an object MUST be present in a response if errors were encountered during the execution. The xml format of diagnosis is described in the SData protocol in the 3.10: Error payload section.
The JSON format of the diagnosis objects supports the following properties:

DescriptionCompliance
$severitySeverity of the diagnosis entry. Possible values are:
  • Info
  • Warning
  • Transient
  • Error
  • Fatal
MUST
$sdataCodeThe SData diagnosis codeMUST
$applicationCodeApplication specific diagnosis codeMAY
$messageFriendly message for the diagnosisSHOULD
$stackTraceStack trace - to be used with careMAY
$payloadPathXPath expression that refers to the payload element responsible for the errorMAY

An example of a diagnoses JSON object is shown below:

{
    "$diagnoses": [
        { 
            "$severity": "error", 
            "$sdataCode": "BadWhereSyntax", 
            "$message": "Invalid query syntax",
            "$applicationCode": "2403"
        } 
    ] 
}

JSON tracking

The tracking object MUST be returned by a provider in response of an asynchronous operation. SData describes a set of properties that can be provided in a tracking object. For JSON, these are:

DescriptionCompliance
$phaseEnd user message describing the current phase of the operation.MAY
$phaseDetailDetailed message for the progress within the current phase.MAY
$progressPercentage of operation completed.MAY
$elapsedSecondsTime elapsed since operation started, in seconds. MUST
$remainingSecondsExpected remaining time, in seconds.MAY
$pollingMillisDelay (in milliseconds) that the consumer should use before polling the service again.MUST

An example of a tracking JSON object is shown below:

{
    "$tracking": {
        "$phase": "Archiving FY 2007", 
        "$phaseDetail": "Compressing file archive.dat", 
        "$progress": 12.0, 
        "$elapsedSeconds": 95, 
        "$remainingSeconds": 568, 
        "$pollingMillis": 500 
    } 
}

1. will be described in detail in another paper on JSON metadata and its usage.
2. will be described in detail in another paper on JSON metadata and its usage.
3. will be described in detail in another paper on JSON metadata and its usage.

Previous Page Arrow Next Page Arrow