Arvados

h1. Hacking SDKs

{{toc}}

h2. Basics

APIs use REST over HTTP and websockets.

We try to be (mostly) compatible with Google APIs. If there is a Google API client library (or library generator) for your language of choice, that is probably a good place to start.

Discovery document

* The discovery document is generated by the API server at runtime, and tells you what the API methods and schemas are.

* The "discovery document specification":https://developers.google.com/discovery/v1/reference/apis is mostly followed.

* In a language like Java or Go, you use the discovery doc to generate a client library.

* In a language like Ruby and Python, you can load the discovery doc at runtime.

h2. Gotchas

h3. SSL certificates

Stock Google SDKs (and HTTP libraries) make it difficult to disable SSL certificate/CA verification. This can make development and testing awkward. This is generally the first hurdle. You could get unstuck by adding your test/dev server's SSL certificate to the relevant HTTP library's "trusted certificate" store, but (so far) there's always been a way to disable verification at runtime as indicated by the ARVADOS_API_HOST_INSECURE setting.

h3. Authorization

No need to think too hard about OAuth2 at this point. Just put ARVADOS_API_TOKEN in the Authorization header of each request, like this:

<pre>

Authorization: OAuth2 abcd1234apitokengoeshere1234abcd

</pre>

h3. Request body

Where [most] Google APIs put a single JSON-encoded object in the *request body*, we accept a JSON document with zero or more objects. For example, instead of this:

<pre>

{"link_class":"test"}

</pre>

we do this:

<pre>

{"link":{"link_class":"test"}}

</pre>

This is expressed in the discovery document, but stock Google SDKs don't tend to understand it.