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

[Jiri Kremser]

Hello,

I hit this issue so I'd like to 'reopen' the topic.

What about introducing a new repo only schemas and swagger docs. Not to mix it with the bus (dumb pipes principle). Currently the swagger is auto-pushed here https://github.com/hawkular/hawkular.github.io/tree/swagger and I think it's not perfect.

We need some shared API/serialization contract. The minimum is having it for the msg format. However message is often composed of concrete entities, arrays of entities, etc. We can go further and leverage the fact of composability. If we have schema for X it's easy to derive the schema for List<X>. I think each component should be autonomous enough and have right to define its own entity classes, but why to repeat all the time definition of, say, the resource? 

If there is an agreement how resource should look like, we can define it in the schema (possibly with a version).

Is 1 json message something like DTO (ad-hoc format, almost no patterns) or rather set of smaller well-defined "sub-messages" (possibly entities)? Of course, I am not talking about those stupid messages with something like "{ "result": 12 }".

wdyt?


----- Original Message -----
| From: "Stefan Negrea" <snegrea at redhat.com>
| To: "John Mazzitelli" <mazz at redhat.com>
| Cc: hawkular-dev at lists.jboss.org
| Sent: Friday, February 27, 2015 7:28:25 PM
| Subject: Re: [Hawkular-dev] generation of message POJOs via JSON schema
| 
| 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
|