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

[Michael Burman]

Hi,

My implemention for hawkular-metrics is waiting in:

https://github.com/hawkular/hawkular-metrics/pull/158

mvn compile -Pdocgen does the job (creates json-files to the generated/ directory as well as transforms from json to asciidoc with mustache).

  - Micke

----- Original Message -----
From: "John Mazzitelli" <mazz at redhat.com>
To: hawkular-dev at lists.jboss.org
Sent: Friday, 27 February, 2015 9:54:46 PM
Subject: Re: [Hawkular-dev] generation of message POJOs via JSON schema

I found writing the schema and generating the code to be fairly painless. But I'll look into the swagger stuff - does anyone have links for examples on how to use its maven plugin to take code and generate json schema from it? What annotations does it use?

----- Original Message -----
> 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
> 
> 
_______________________________________________
hawkular-dev mailing list
hawkular-dev at lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev