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

[Stefan Negrea]

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
>