Re: [Hawkular-dev] generation of message POJOs via JSON schema

I also like the idea of using schema for documentation. I agree with Stefan that the individual subprojects/services should own the schemas if we want them to loosely coupled and be able to version them independently. With respect to documentation, I think good API tests are really important, at least for developer docs. Tests that are expressive and self-documenting can be a form of executable documentation. I came across an articular which said that Heroku has schema endpoints. With metrics for example, we might have a GET /hawkular/metrics/numeric/data/schema endpoint which returns the schema for the /hawkular/metrics/numeric/data endpoint. This might be pretty useful. > On Feb 27, 2015, at 1:28 PM, Stefan Negrea <snegrea(a)redhat.com&gt; wrote: > > Hello, > > Very seldom REST API's come with schemas; the typical workflow when working > with REST: > 1) read documentation about the rest end-point > 2) if the project has a test site, try a few live queries > 3) Write application code (TDD or not) > 3.1) if something is wrong with the request, the service will return an > error; read the documentation again > 3.2) if something is wrong with the reply (not what expected), then read > the documentation again > 4) Add plenty of integration tests > > This workflow gets simplified if the project provides an SDK for > integration; but not by a lot, there is still documentation to be read, > tests, errors, etc. > > Because of JSON's ease of use and the possibility of implementing the > client in many languages/frameworks, the schemas are no longer relevant. > Good documentation (with examples), good REST API design, good errors, a > live test tool, and an SDK are far more important. > > Here are a few samples on how Google, Facebook, Twitter, ans AWS approach > this: > 1) Documentation: > https://developers.facebook.com/docs/graph-api/reference/v2.2/album/photos > 2) Documentation: > https://developers.google.com/accounts/docs/OAuth2WebServer > 3) Test Tool: > https://developers.google.com/apis-explorer/#p/blogger/v3/blogger.blogs.g... > 4) Documentation: > https://dev.twitter.com/rest/reference/get/statuses/home_timeline > 5) SDK: http://aws.amazon.com/sdk-for-python/ > > With all this being said, here is how I would see using these tools in > Hawkular: > 1) Do all the work in the individual projects (write classes; annotated > classes if necessary). > 2) Use a tool to generate schemas from code > 3) Make the schemas definitions part of the documentation or SDK > > > I like the concepts from swagger tool that Micke talked about because you > can drive the schema generation from the code. Now if we find a tool that > is bi-directional, that's even better. The users and community members > could then use the schemas to generate our code for their own applications > to interact with Hawkular. > > > Now, one thing that I would be very concerned to see is transforming the > bus into a central repository and source for schemas. The bus should be > designed following the "dumb pipes" [1] principle. It should take care of > delivery but never ever inspect or make decisions based on actual content > piped. > > [1] > http://martinfowler.com/articles/microservices.html#SmartEndpointsAndDumb... > > > > Thank you, > Stefan > > > ----- Original Message ----- >> From: "John Mazzitelli" <mazz(a)redhat.com&gt; >> To: hawkular-dev(a)lists.jboss.org >> Sent: Thursday, February 26, 2015 3:35:52 PM >> Subject: Re: [Hawkular-dev] generation of message POJOs via JSON schema >> >> Here's an example PR that can show where we can build this "glue code": >> >> https://github.com/hawkular/hawkular/pull/31 >> >> It's a JSON schema with generated POJOs. In this case, it is just the >> metrics. Stefan mentioned he'd rather the metrics provide this - which is >> fine, we don't have to merge this PR - we just do something similar in the >> metrics repo rather than in the hawkular project itself. >> >> But the point is, this shows how we can produce a small jar with just the >> JSON schema files and the Java classes that represent those JSON objects. >> These generated POJOs play nice with the bus infrastructure and the API we >> are using to produce/consume messages. >> _______________________________________________ >> hawkular-dev mailing list >> hawkular-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hawkular-dev >> > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev