Hacking SDKs¶

• Table of contents
• Hacking SDKs
  • Basics
  • Gotchas
    • SSL certificates
    • Authorization
    • Request body

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.
• 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.

Gotchas¶

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.

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:

Authorization: OAuth2 abcd1234apitokengoeshere1234abcd

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:

{"link_class":"test"}

we do this:

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

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