APIPythonOpen-Source Solutions

I'm trying to generate some source code objects (currently Java) from the JSON schema I found for our API version. I've tried a few tools (like jsonschema2pojo) but have encountered errors and have been unable to successfully do so. Any tips on how to accomplish this?

Perhaps a larger question on the provided JSON schema is exactly how to use it. I'm not quite sure if it's a strict schema definition or is meant to be treated as a discovery service (a type of HATEOAS...a good demonstration of which is shown here). Should the API be treated as a dynamic discovery service that may have changes made to it down the road--and therefore any client should develop from HATEOAS perspective? The specific API version is passed in the session creation, so am I overthinking this?

Thanks!

Hi Ross,

You can consider Delphix Engine sessions initiated with a specific API version to be static and stable.

The Delphix Engine expects clients to specify an API version when they initiate a session. The Delphix Engine will use this API version to interpret input from the client and modify output sent to the client. The idea here is that the client can be implemented once against a specific API version and if the Delphix Engine is upgraded later down the road, the client will not need to be rewritten to accommodate slight API changes introduced by the upgrade. The Delphix Engine will "translate" all input and output JSON to match what the client expects.

We do not currently support compiling our schemas to Java (though publishing language-specific API bindings is something we'd like to do in the future!).  Our schemas are stable and loosely based on the JSON Schema draftV3 specification, but are not fully compliant such that third-party tools can generate code from them.

For now, you will need to implement your own Java classes on top of our API specification. While doing this will require significant effort, your Java code should remain compatible with all Delphix Engine versions released in the foreseeable future as we guarantee backwards compatibility with future releases.

Let me know if you have any follow up questions!

Thanks for the follow-up, that makes sense! I had the questions on HATEOAS because I couldn't figure out the schema syntax so I thought it might be a discovery service. JSON schema v4 would be a nice feature enhancement :)

Out of curiosity, what are the JSON schema definitions used for? Are they used for generating the documentation on the engine server (/api/)?

Thanks again!

We consume the  schemas internally with a tool augmented to understand the non-compliant portions of what we publish. The schemas produce "/api" and are also used to validate JSON sent to the Delphix Engine.

Since the schema format is fairly stable, we publish the JSON schemas with every release in case someone is motivated to consume this data. Though, as you can see, consuming this JSON is far from trivial. Making schema consumption easier is definitely something we are looking to improve moving forwards.