Project

General

Profile

Hacking SDKs » History » Version 2

Misha Zatsman, 05/19/2014 08:53 PM

1 1 Tom Clegg
h1. Hacking SDKs
2
3
{{toc}}
4
5
h2. Basics
6
7
APIs use REST over HTTP and websockets.
8
9
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.
10
11
Discovery document
12
* The discovery document is generated by the API server at runtime, and tells you what the API methods and schemas are.
13 2 Misha Zatsman
* The "discovery document specification":https://developers.google.com/discovery/v1/reference/apis is mostly followed.
14 1 Tom Clegg
* In a language like Java or Go, you use the discovery doc to generate a client library.
15
* In a language like Ruby and Python, you can load the discovery doc at runtime.
16
17
h2. Gotchas
18
19
h3. SSL certificates
20
21
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.
22
23
h3. Authorization
24
25
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:
26
27
<pre>
28
Authorization: OAuth2 abcd1234apitokengoeshere1234abcd
29
</pre>
30
31
h3. Request body
32
33
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:
34
35
<pre>
36
{"link_class":"test"}
37
</pre>
38
39
we do this:
40
41
<pre>
42
{"link":{"link_class":"test"}}
43
</pre>
44
45
This is expressed in the discovery document, but stock Google SDKs don't tend to understand it.