The JSON Compare REST Service Guide

1. Introduction

The JSON Compare REST service allows you to invoke JSON comparisons from a wide range of programming languages and systems.

The service currently provides a free usage tier using DeltaXML's infrastructure, however the same, or a very similar REST API will be available in other forms as such a paid-for usage tiers providing higher usage levels on a more resilient infrastructure and also running the service locally on customer/private servers. Please see our roadmap or contact us to discuss the roadmap further.

This document will describe the service and how to develop applications using it.

2. Free Usage Tier

The free usage tier allows evaluation and experimentation prior to large scale deployments using future paid tiers or on-premise deployments. It also allow small-scale production use, but without any service level agreements or other guarantees of service availability or provision.

The tier is currently based on an operation metric. Each operation increments a usage limit counter, that once reaching a set permitted usage level will return an appropriate error. The counter is reset every 30 days.

The current free usage tier allows 1000 operations per 30 days. The current usage level can be viewed at: https://www.deltaxml.com/json-client/usage
There is also a REST /usage resource that can be called to determine the usage level within an application. On request we may be able to increase the allowance on a one-off basis for a month or an ongoing basis; please contact us to discuss your requirements.

3. Experimentation using Postman

We have provided a Postman Collection that allows easy experimentation of REST requests and responses with simple example data. It has been documented here.

4. Experimentation using the Web Client

A web client is available that allows developers to explore the capabilities of our change representation or 'delta format' for JSON. It allow developers to paste or drag-and-drop small JSON examples (see: Free Usage Limits) and see various linked representations of those inputs and the comparison results so that where changes are reported in the delta the corresponding locations of the data in the inputs are also highlighted.

We recommend using this web client in conjunction with our format documentation when exploring and experimenting with our change representations.

There is also documentation for this client.

5. Using OpenAPI/Swagger for Documentation and Clients

An OpenAPI definition of the REST interface is available at our public Bitbucket repository.

This definition can be loaded in the Swagger Sditor: http://editor.swagger.io/#/ to view online documentation. It is also possible, after supplying an authorization token to experiment with the REST API, however we have found the Postman Collection easier to use.

Additionally, Swagger Codegen can be used to generate client API libraries for a wide range of programming languages. We have made use of this generator with some command-line clients that we provide. Other programming languages and systems are available, but we have not tested or can provide support for these.

6. Samples

We provide a number of samples for use in conjunction with the service. These are either code samples which illustrate how JSON deltas can be processed or command-line applications for various platforms/systems.

The samples are not supported or licensed as part of the REST service and are available in source code from our Bitbucket account. While we cannot offer any support guarantees for our samples we welcome issue reports and also pull requests for suggested improvements and bug fixes.

6.1. Command Line Applications

7. Authentication

Use of the service through the web client or the REST API requires authentication. Authentication for REST requests makes use of JWT authentication tokens. By using the "Download ID Token" menu option of the Web Client you can download a file containing an ID Token (under the key "id"), a Refresh Token (under the key "refresh") and the ID Token's expiry (under the key "expiry"). ID Tokens remain valid for 10 hours, and command line clients we provide will automatically refresh the ID Token if it has expired.

8. Free Tier Service Limitations

Various limitations are in place in order to provide a reliable service to a number of users with the free usage tier. Future paid SaaS tiers on more scalable infrastructure or on-premise offerings may relax these limitations.

8.1. Web Client Limitations

The current web client performs poorly when trying to display and synchronize changes for large JSON inputs. A download and copy result to clipboard facility when the input size exceeds 50 KB is provided as an alternative to the synchronized display. We are working on performance improvements for our synchronized result display in the client and will increase this limit as we resolve these issues. The clipboard and download facility may also be retained when the limit is increased.

This is a client-only limitation and the REST service itself is capable of processing much larger inputs.

8.2. REST Service Limitations

The REST service free usage tier has limits in place:

  • to provide a reliable service for many users
  • to ensure our hosting and bandwidth costs are constrained
  • to provide opportunities to monetize future paid for usage tiers as part of a more robust/scalable SaaS offering

When you hit your usage limit for number of comparisons, you will receive a HTTP 400 Bad Request response, with a JSON response containing an error message "Monthly usage limit reached." with the key errorMessage.

You can also check your usage details from the endpoint /usage which returns a JSON object. The key usage contains your current number of used comparisons, permittedUsage contains your permitted usage limit. startPeriod and endPeriod respectively document the start and end of your usage period.

Example of usage details object
{
 "usage": 7,
 "permittedUsage": 1000,
 "startPeriod": "2017-05-23",
 "endPeriod": "2017-06-21"
}

As well as a monthly limit on the number of comparisons the size of each of the two comparison inputs is currently limited to 5 MB. This limit is subject to change. When you hit the size limit, you will receive a HTTP 400 Bad Request response, with a JSON response containing an error message "JSON Input A exceeds 5000000 character size limit." (A or B where applicable) with the key errorMessage.

9. Data Retention and Confidentiality

The following statements relate to the REST service and API in its current form.

  • We do not store or otherwise retain any JSON data that is provided to the comparison service.
  • We do not believe that other service users can access your input data or comparison results with or without access to your authentication token.
  • We record the operations performed and the parameters used for each comparison in order to measure and control usage and guage the popularity of the various operations and parameters/settings.

10. Support

Please raise issues related to our sample clients and applications on their respective Bitbucket issue trackers. For issues relating to the service itself and questions about the change representation and its application we have a dedicated JSON Compare channel in our Support Forums.