Define backwards compatibility criteria

[yurishkuro]

Once we release 1.0 version, there will be stronger expectations of backwards compatibility. We need to enumerate what they are and have some way of validating them.

[omeid]

Please also make sure that you tag the relevant docker images as well whenever there is a breaking change :)

[pavolloffay]

How are we going to version REST API? Using URI or header?

Currently we have api/traces?format=jaeger.thrift. I would rather see something like api/v1/traces/ and then distinguish based on content type. Zipkin API could add another path segment or we could just use zipkin path (api/v1/spans). IIRC we don't report data to that endpoint from our clients.

[yurishkuro]

while we are on 0.x releases I'd stay away from /v1/, but in the future - yes.

IIRC we don't report data to that endpoint from our clients.

How do you mean? We (internally) are using HTTP endpoint with jaeger.thrift to submit spans from outside of out data centers (from cloud based blackbox monitoring).

[pavolloffay]

How do you mean? We (internally) are using HTTP endpoint with jaeger.thrift to submit spans from outside of out data centers (from cloud based blackbox monitoring).

To zipkin endpoint.

[yurishkuro]

I think we should decommission /api/traces?format=zipkin.thrift since we support Zipkin API directly on the new port

[pavolloffay]

@yurishkuro agree /api/traces?format=zipkin.thrift will be removed here https://github.com/uber/jaeger/pull/282#discussion_r129329071

[omeid]

I think it would be better to have the version as part of the content type and do proper content negotiation instead of sub resource scoping.

[yurishkuro]

@omeid can you point to prior art?

[jpkrohling]

@yurishkuro was this completed for v1? Now that the model we use for gRPC is stable, it would be a good time to document what are the backwards compatibility expectations.

[yurishkuro]

still waiting for Query service gRPC API

[annanay25]

This can now be revisited