Document the v1 REST Api

[codefromthecrypt]

The query server presents a REST api under the /v1 namespace. This needs to be documented.

It is a good time to do this, as we don't expect many major changes. Major changes would coincide with our v2 model https://docs.google.com/document/d/1ixxEs9TvhiGjJObGbRSPhSna3zHdadoUTQIZ5JKgLzU/edit

[codefromthecrypt]

UPDATE: did a lot of research and backfilling code docs, which will be where most of the rest docs are harvested from. Anyone needing insight into the model before this issue closes can look here: https://github.com/openzipkin/zipkin/blob/master/zipkin-thrift/src/main/thrift/com/twitter/zipkin/zipkinCore.thrift#L272

[codefromthecrypt]

Update: I've reviewed tools and will spike this with apiblueprint https://apiblueprint.org/

This seems to fit the task of api portability and align with the fact that we have active contributors on markdown, who regularly get scared off when asked to look at scala or thrift files :package:

Moreover, apiblueprint has a tool called dredd which can be used to test fixtures. I'm wondering if this could be leveraged to help test tracers... https://github.com/apiaryio/dredd

@netmilk might ask you to help review something once I try this out. Short of it is that zipkin has 2 api server implementations at the moment, scala and java. We have clients (tracers) in many languages including scala, java, ruby, c#, python and some lesser maintained ones like node. Documenting the api is the first win, but a second one would be to use travis to test it.

cc'ing folks who've expressed interest in or contributed to our docs: @abesto @kjoconnor @jfeltesse-mdsol @clehene @zfy0701 @dsyer @jamescway

[abesto]

Sounds like a good direction to me. I'm planning to factor out a general python client from https://github.com/prezi/django-zipkin and create Flask bindings early next year with @deathowl; we can turn that into a test-drive for this.

[codefromthecrypt]

here's a start, cherry-picking the easiest methods while I get used to things https://github.com/openzipkin/zipkin/pull/888

[yurishkuro]

@abesto I just finished python instrumentation for urllib2, sqlalchemy, and tornado async client, if there's interest. We're planning to open source that soon, although I'd prefer to adjust the API to match opentracing. django-zipkin seems to only have the middleware, not the client call site instrumentation?

[netmilk]

@adriancole I think it's a great idea! The possibility to let non native programmers edit the documentation and be sure it's still valid is the win of using Dredd.

The idea behind Dredd is be able abstract the discussion about the HTTP API to the lingua franca contract - the API Blueprint, but keep it tightly bound to the implementation with hooks and tested in CI (!), so it won't get out of sync.

I think the only catch in your case can be Dredd doesn't support Scala or Java at this moment. But it has precedent support for compiled language (Go) and tutorial support for adding new language including the language agnostic testing harness so it shouldn't be a problem to add your's if needed.

I'm excited to help with anything. Just ping me here, on twitter (@ntmlk) or we can schedule a little call if needed.

[abesto]

@yurishkuro That's great, I'll reach out when we get down to it to make sure we converge the APIs. django-zipkin has call site instrumentation, documented at https://github.com/prezi/django-zipkin#recording-annotations.

[netmilk]

@adriancole I just had a look at the API Blueprint document in #888. I don't know how does the entire API looks like but it API seems to be quite simple to eme. If it has only GET methods you could probably seed it with some script before Dredd execution and any sophisticated isolation of each action with hooks shouldn't be necessary.

[codefromthecrypt]

@netmilk thanks for the feedback.

There was a discussion on gitter about apiblueprint vs swagger:

Voting for swagger: @prat0318 - has experience with swagger and prefers swagger doc integrated with query apis. Noted visual editor @karlunho - works at a company that makes OSS tooling for swagger. Notes higher adoption numbers

Abstain: @yurishkuro - no experience with either apiblueprint vs swagger @abesto - limited experience with swagger, none with apiblueprint. Noted ttps://github.com/cachecontrol/hippie-swagger, which can be used to create tests.

me - no experience with either, interested in testable, easy to write api docs. I'd like a solution that can be run with travis, and treats services as black boxes (ie tests go off spec as opposed to requiring frameworks on the server). apiblueprint/dredd seems to have that, but that doesn't mean hippie-swagger or otherwise don't. Regardless, I've not gotten to the point of even using dredd to validate the travis-black box ability.

[codefromthecrypt]

PS it is totally my goal to re-use whatever framework we make for a v2 api. I'm using v1 as it is the only thing we have implemented, and what all the current tracers are built on.

[prat0318]

I think api-docs tool should not be coupled with e2e testing tool. api-docs tool should be judged on its expressionability. A decent enough e2e testing framework should be easily plugged in with any of the api-docs tools or can be also tested directly with endpoints (not sure how api-docs help there).

I haven't have an experience with blueprint so can't comment much. But i would say, a feature to explore APIs and test them directly (like here) comes handy a lot of times.

[codefromthecrypt]

looks like swagger is now https://openapis.org/

[codefromthecrypt]

@karlunho offered to take a stab (or faciliate one) w/ openapis.

To help, I'm making a google doc of curl commands https://docs.google.com/document/d/14Ucxk-K1JhWE60Xry2XZak5fHrBagJT-HCMbo_iou18/edit?usp=sharing

[prat0318]

@karlunho++ i will be happy to help/review the swagger apis.

[codefromthecrypt]

cool.. glad you all are interested. if not I'd feel silly as making the google doc to prepare for swagger is slightly more work than writing the api blueprint format. This extra effort is worth it, if we're likely to have a more sustainable, shared outcome

[codefromthecrypt]

I've updated the doc with all endpoints.. ready for swagger/apidocs conversion https://docs.google.com/document/d/14Ucxk-K1JhWE60Xry2XZak5fHrBagJT-HCMbo_iou18/edit#

[karlunho]

Will look at this over the weekend

[codefromthecrypt]

https://github.com/openzipkin/zipkin-api !