Run Diferencia

To start diferencia you only need to run next command from your terminal:

~$ diferencia start -c http://rest.ensembl.org -p http://rest.ensembl.org

This command just starts Diferencia proxy, configuring it to use http://rest.ensembl.org (-p) as the primary (old version) and http://rest.ensembl.org (-c) as the candidate (new version).

Then run next curl command:

curl 'http://localhost:8080/info/ping' -H 'Content-type:application/json' -i

And the response is HTTP/1.1 200 OK because obviously, both are the same version so they are producing the same output.

What is happening under the cover when you do that curl operation is that Diferencia proxy replaces the host with primary host and sends the request to it (http://rest.ensembl.org/info/ping) and then do the same with the candidate host, sending the request to it (http://rest.ensembl.org/info/ping).

After that, both responses are compared and if they are strictly equal then an HTTP 200 OK method is returned from the proxy.

In the previous example, both responses must be strictly equal (this means that JSON schema and each key/value must be equal).

But there are other modes that we are going to describe in next sections:

If you have Diferencia started from Starting Diferencia section, stop it and start it again with next command:

diferencia start -c http://now.httpbin.org/ -p http://now.httpbin.org/

Now we are configuring Diferencia proxy to redirect requests to http://now.httpbin.org/ which basically returns the current time.

So you can run next curl operation:

curl 'http://localhost:8080/' -i

And the response is HTTP/1.1 412 Precondition Failed. This is happening because although you are sending the request to the same service, it is returning the current time which of course it is not the same in both calls. This thing that it is pretty obvious makes that Diferencia result is a failure, saying that both services are not compatible (so there is a regression), when the truth is that they are equally valid, but having a value different.

To fix this there is a noise cancellation algorithm that detects these dynamic values and suppress them from JSON document. This algorithm sends the request to not two instances but three. Two are the old instances (primary and secondary) and one to the new instance (candidate).

The request to primary and seconday returns a valid request (since old instances are the correct ones), then from their responses, Diferencia checks for the differences between both responses.

Since both responses are valid (because the source is the same but different instances), the differences that are between them are just noise that should not take into consideration for response validation.

Then detected noise is removed from primary and candidate response, and they are compared, if they are equal, then you know that everything is fine.

This can be summarized in next schema:

Now stop Diferencia and start it again with next command:

diferencia start -c http://now.httpbin.org/ -p http://now.httpbin.org/ -s http://now.httpbin.org/ -n

You are setting URLs for primary (-c), secondary (-s), candidate (-c) and finally that you want to enable noise reduction (-n).

Now just execute the same curl command as before.

curl 'http://localhost:8080/' -i

And now the response is totally different returning a 200 OK.

In next table you can see all possible configuration arguments that you can pass to Differentia: