API Documentation — an adventure with Google Drive
Everyone knows the importance of documentation in software development. It’s beaten into software developers at University, by their peers and through the frustration of using poorly documented or undocumented libraries. Over the past decade it’s become even more critical with the move to open APIs designed to drive greater adoption of your services. Obviously this extends beyond documentation, an API ideally should:
- Be well documented
- Be simple to use
- Predictable and consistent
- Provide SDKs for major languages (Python, Java, JavaScript, .NET, etc)
The documentation should:
- Provide a complete reference
- Provide examples using the major languages where an SDK is provided
- Include request/result examples and clear descriptions of expected responses
- Provide a basic complete example (to get started)
- Be logically structured
There are some great examples out there (Stripe’s API, though I’ve not used, it is beautifully documented).
Google Drive API v3 Documentation
Now on to Google. They have done a great job in trying to provide documentation, right through to the ability to test out API calls through the documentation pages. But in my opinion it falls short. I find myself having to move about several sections to understand various components. Also I find examples (example requests and responses) incredibly valuable when working with an API, which seem to be hard to find.
The Complete Reference:
Found in a couple of places, in two major formats. The API Explorer provides a way to find a reference of all the available Google APIs. And the API Reference provides a prettier view with the ability to try the API (awesome!).
The examples using the major languages:
Not so great, small examples found littered through the API Guides. At least they are provided in the major languages.
The request/result examples:
Basically doesn’t exist! The API Explorer kind of provides some weak descriptions. And using the “Try this API” on the API Reference you can get some idea. But I’ve found there are a lot of cases when fields are empty when you might think there should be data.
The basic complete example:
Not bad here. You can get quick start guides like the Python Quick Start. Also a couple of Complete Samples.
The logical structure:
Information is all over the place! The API Explorer merely lets you view the API calls available, with no description. The API Reference gives you a way to try the API calls but has little to no description. The API Guides provide some overview/description (under the Concepts header), but are generally weak and provide few examples. There are a few hidden gems though!
Other notes:
The documentation isn’t complete without the API Client Libraries Guides. These guides provide an overview of using the SDK including important implementation information like OAuth2.
You also need to know about what scopes are available, which are found at the Google Scopes page and on the Concepts > Authorization page.
Using the Google Drive API v3
If you’re starting fresh with the API here is where I would suggest you start:
- Check out the quick start guide, e.g. Python Quick Start
- Read about using the SDK and the higher level concepts (Auth, Pagination, etc) API Client Libraries Guides
- Read through the concepts and guides at the API Guides
- Use the API Reference and API Explorer (the “what”) in conjunction with the API Guides (the “why/how”). Don’t miss the Standard Query Parameters!
- Use the “Try this API” section in the API Reference.
- Look for the hidden gems like the Push Notifications Playground (V2 unfortunately) for testing the web hook for detecting changes in Google Drive.
I’ll follow up soon with a few specific examples for using the API!
