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

[John Sanda]

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 at redhat.com> 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.getByUrl
> 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#SmartEndpointsAndDumbPipes
> 
> 
> 
> Thank you,
> Stefan
> 
> 
> ----- Original Message -----
>> From: "John Mazzitelli" <mazz at redhat.com>
>> To: hawkular-dev at 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 at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>> 
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev