Google API Wrapper

These are some notes describing the intuition behind the contents of /src/web/js/google-apis/api-wrapper.js. It describes a comparison of the calling conventions before and after the library was implemented.

Consider the following call:

var foo = drive.permissions.insert({
  fileId: newFile.id,
  resource: { ... }});

Now foo is an object representing a request to a Google API, but nothing will happen until foo.execute(callback) is called.

Suppose we call foo.execute and we are not authenticated. We will then get back something like a 403 error. Instead, what we would like to do is have some sort of authCheck function that we can pass a callback to call once we are sure that the user is actually signed in (whether that means signing in with Google or getting a new token from the Pyret endpoint). Now suppose that, for whatever reason the authentication fails. The result of foo.execute will then be a JSON object o such that o.error !== undefined. Thus, we have authCheck return a promise which is passed to a failCheck function that throws a JS error if foo.execute returns an error object.

In addition to playing with the OAuth access token (i.e. allowing non-authenticated queries, if desired), this is what gQ does; returning a promise which resolves to the failCheck-ed and authCheck-ed result of calling foo.execute.

Thus, the convention for using foo in the ​original​ implementation would be

var res_promise = gQ(foo);

The catch here is that, with the way that the GAPI stuff was structured, all three of these functions would need to be re-implemented for every gapi-using API wrapper. This was the first inefficiency this library addressed: these functions were lifted into their own library to allow reuse. The following then became apparent:

1. There is never an instance in which a GAPI request (like foo) is not ​immediately​ followed by passing said request to gQ
2. => gQ really should just wrap all of those calls by default

This was the main innovation of this library: gwrap.load. This works in the following way:

1. Take note of all keys belonging to gapi.client.
2. Call gapi.client.load with the appropriate arguments to load the desired library
3. Once that is loaded, check which keys have been added to gapi.client (these are the new API functions)
4. Add those keys to gwrap, but, if a property is a function, then wrap that function with a call to gQ before adding it to gwrap.

Thus, gwrap auto-wraps every API method with a call to gQ. This means that the calling convention in the ​new​ implementation would just be

var res_promise = foo;

References

1. API Client Library for Javascript (Beta): 2015. https://developers.google.com/api-client-library/javascript/reference/referencedocs. Accessed: 2016- 05- 22.