JSON Support

Article
05/18/2015

Windows Azure Marketplace (WAM) enables JSON support for WSPF and JSON/P support for all WAM services. Such support is important for creators of applications that want to request data cross-domains.

JSON support for Marketplace services

Applications specify that they require a JSON response by adding a $format parameter to their request URL.

Note

Important

The Marketplace supports OData 2, not OData 1.

The $format parameter

The $format parameter is optional. When provided, it specifies the return format for a Marketplace dataset. Supported values are “json” and “atom.” If the parameter is omitted, the Marketplace returns an ATOM response.

`$format` included	`$format` value	Response
No	N/A	ATOM
Yes	atom	ATOM
Yes	json	JSON
Yes	Any other value	Error

The following example requests the response in JSON format.

https://api.datamarket.azure.com/Services/All/Datasets?$format=json

JSON/P support for Marketplace services

Applications are able to request and received data crossdomain using JSON/P.

The $callback parameter

The $callback parameter is optional for requests, but is required for JSON/P requests. It can only be used with $format=json, otherwise the request is invalid and fails. When you specify the $callback value the Marketplace pads the JSON format with a call to the JavaScript method specified in the $callback value.

For example:

Request	`$format=json`	`$format=json&$callback=myMethod`
Response	`{'x1':'A', 'x2':'B'}`	`myMethod({'x1':'A', 'x2':'B'})`

The JSON/P formatted result automatically causes the JavaScript engine in the browser to trigger the callback method once the data download is complete. Thus, the developer can include a <script> tag that points directly to the data source and trigger code without the need to manage XmlHttpRequest callbacks or other infrastructure.

For example,

<script type="text/javascript"
src=https://api.datamarket.azure.com/Services/All/Datasets?$format=json&$callback=response>
</script>

`$format`	`$callback`	Response
Not present	Present	Error
Something other than json	Present	Error
json	Not present	JSON
json	JavaScript identifier	`<name>(JSON)`

The accessToken parameter

The accessToken parameter enables you to pass the OAuth Access Token to the Marketplace through the URL rather than through HTTP headers. In turn, you are able to include all the data required to obtain data in the src attribute of a script tag. This also provides a convenient workaround to scenarios in which some browsers prevent downloading content from other domains when the necessary information is passed through HTTP headers.

Important

After getting the OAuth token, developers UrlEncode it and pass it to the parameter accessToken.

For example:

<script type="text/javascript"
src="https://api.datamarket.azure.com/data.gov/crimes/CityCrime?$filter=City eq 'Seattle'&$format=json&$callback=response&accessToken=...">
</script>

Obtaining a WAM access token

To learn about obtaining an access token, look here: Implement OAuth in your Marketplace App. Web applications that take advantage of the new JSON/P feature must implement an OAuth Authentication flow that causes a user to log in and to grant access to their Marketplace subscription. The refresh token for that user can then be associated with that user’s identity on the web application and can be used to obtain new Access Tokens each time an old access token expires.

Share via