Consuming complex JSON service that does not have schema

Question

Hi I have this weird situation where I have a JSON producing service that represents a very complex object graph and this bject graph does not have a JSON schema that it is based on. The reason for this is because originaly there is an EJB service and this REST service is just build on top of it with simple 1:1 mapping in between objects.

Since I don't have a contract for this service I see 2 options:

1. Import the DTO-s from the producer project directly into my consumer project in which case every change on the DTO-s in the producer project potentialy may be a breaking change for my module.
2. Use some generic API for the JSON object as JsonObject f.ex.

My question. Do I have a good alternative when I need to read complex object structure from JSON and I don't have a JSON schema to generate my Java objects ?

Is there any point into trying to describe the incoming input on the recieving side of the JSON ?

Answer 1

Just to set your expectations for the future, this is far from rare. Indeed, JSON Schema and OpenAPI are rather recent developments, and part of the appeal of JSON over XML was that it had a few basic types baked in, and supposedly didn't need the complexity of complex enterprise schemas.

In some cases, the producer of an API might provide an SDK for the language you're writing a client in (i.e. a set of classes or functions that map requests and responses for you). In others, they might provide a schema in a format that you can use to produce one for yourself automatically (e.g. an OpenAPI service description, or a set of JSON Schema definitions).

If they provide neither, you have a few options:

• Create your own "SDK" by hand, based on whatever documentation they do provide.
• Create a schema or service description based on their documentation, and then use that to build an SDK.
• Do without an SDK, and use untyped objects for the requests and responses.

Whichever of these you use, you are going to have to write some "glue code" anyway, to map the API-oriented data into the objects needed for your business layer.

In some cases, you only want a small fraction of the available fields anyway, so extracting those from something generic like a "JSONObject" will be more efficient (in terms of programmer effort) than hand-crafting an object that represents all the details that the API can technically return. One thing to watch out for in that case is that the glue code will need to have more "defensive" aspects, since you don't have a separate layer to perform that validation in.