The JSON Compare REST Service Guide

 Table of Contents

Introduction

This guide is designed for users of JSON Compare

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

What can JSON Compare do?

JSON Compare is a REST service that allows you to invoke comparison of JSON files 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.

For more information:

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. For more information see: Free Usage Tier

Getting Started

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 Editor: http://editor.swagger.io/ to view online documentation of the API's endpoints and parameters, and also generate API clients. 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.

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.

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 Tier) 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.

Code Samples

For information on the samples we have provided: Samples

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.

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 gauge the popularity of the various operations and parameters/settings.

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.

#content .code