API docs and client libraries


Any information on when API documentation will be available, and maybe even client libraries if those are planned?

We have made our own Java client very quickly using Retrofit + Jackson. It’s just a matter of mapping the json objects into Java objects, and map the rest calls using a Retrofit annotated interface.

The rest api is self-documented on http:///v1. Altough, it would be interesting to have a documentation which explains what object is for what. It’s a bit confusing between physicalHosts, hosts, machines etc.

We (well, @denise and @prachi mostly) are working on docs right now to publish in the next week or two.

There are Go and Python libraries that we use internally, and a PHP one I wrote a long time ago. Beyond that we would like to have official clients for more languages but have no immediate plans.

Thank you for the update. I’ll have a look at the Python library while waiting for the docs.

The python client won’t help you much since it’s a generic client to query the GDAPI REST Api.

Every language’s client we make will be generic, (or generically generated code). All of the API is described by the schema it returns, there is no need to write Rancher-specific code for a client library.

(You’re right that it won’t help as far as documentation though.)

It’s not possible to write a completely generic client in Java. The language is not as dynamic as Python or Php. And, at some point, you need to rely on the nature of the objects even with a generic client.

I think the GDapi basically just avoids to hardcode the endpoint urls in the client. It also serves as a micro-documentation about the service and the object structures behind.

@jloisel All of Cattle (the core of Rancher) is Java. The schemas describing every type and field are there specifically to make it possible to generate code for strongly-typed languages like Go and Java, because nobody wants to manually maintain classes for $x APIs * $y resources * $z languages every time a new field is added.

Thanks for the insight. :blush:

Is a Java client planned anything soon? I would be interested since i could then throw away our hardcoded beans and rest api calls.

Is a Java client planned anything soon?

1 Like