Skip to content
Vimond Vimond Vimond Developer Hub

A Note on XML and JSON Formats

❗️ Who is this document for?

This document is intended for:

  • Back-end application developers who need to interact with VIA admin APIs for managing the Content Catalog (assets, categories, lists).
  • Front-end or back-end application developers who need to interact with VIA Monetise APIs for enabling purchase flows in their application (products, product groups, orders, subscriptions).

👍 Who is this document not for?

  • Front-end application developers who are not using VIA Monetise. For such cases, simply use Accept: application/json on all API endpoints.

When using the admin APIs in Vimond REST API for managing the content catalog, data is accepted in both XML and JSON formats. However, we strongly encourage the use of JSON, as XML is not supported in the new services that we develop.

In the older admin APIs, JSON is supported in three different versions. However, in the newer services, only a single standardized JSON version is supported.

The table below describes the different formats and options:

FormatAccept-headerDescription
XMLapplication/xmlThe original API format is now on its way out as the world is standardizing on JSON.
JSON v1application/jsonSupported across asset, category, product setup, and user profile API endpoints.
JSON v2application/json;v=2Supported across most admin API endpoints, with some exceptions.
JSON v3application/json;v=3Supported across most admin API endpoints, with some exceptions.

You can use the Accept HTTP header to set your preferred response type. In the examples provided on this site, JSON v3 is used when available, with fallbacks to XML and plain text.

Here are additional details about the JSON versions:

  • JSON v1 is identified by the .json appendix in API requests (e.g., /api/web/asset/{id}.json). If both v1 and v2 are specified in the same request, v1 takes precedence.
  • JSON v2 always returns an array for a response that may have one or more elements. In contrast, JSON v1 returns one object if the response has only one element, and an array if it has multiple elements.
  • JSON v3 uses the ISO 8601 date format instead of the timestamp in seconds since epoch. Additionally, null value properties are omitted from the JSON objects. Periods on Products and PaymentPlans are serialized as an ISO 8601 duration (e.g., “PT1M”).

Please ensure you specify the appropriate Accept header in your API requests based on your desired format. In the examples listed on this site, we will use JSON v3 when available, with fallbacks to XML and plain text.

Accept: application/json;v=3, application/json;v=2, application/json;v=1, application/xml, text/plain

When posting data to the Vimond REST API using POST or PUT calls, ensure that the Content-Type header is set to JSON v3.

Content-Type: application/json;v=3

If you have any questions or need further clarification, feel free to reach out for assistance.