Category Archives: Android API
This post is one in my emerging series of API basics from a technical writer’s point of view. How does a developer get hold of an API, so that she can use it in her application?
The other day, I was chatting to folks in our Marketing team about the three essential items of information an API quick-start guide should give developers:
- Where to download the API and other tools you need.
- Where to get your API key or other required app credentials.
- A hello world app or some basic sample code.
During that discussion, I realised that the first item (“download the API”) differs depending on the type of API you’re discussing. It’s not always a case of downloading the API and adding it to your development project. Sometimes you don’t need to download anything – you just send a request. Sometimes the download happens each time your application needs to use the API. And sometimes you download something in your development environment and compile it into your application project.
Before the recent discussion, I’d understood the difference subconsciously, but during the conversation it became clear to me that this is something worth bringing to the fore, especially for those of us who need to document or market APIs. It’s a useful way of becoming more familiar with the types of API that we’re writing about. (If you’d like to know more about the various types of API, take a look at my attempt at a tech writer’s classification of APIs.)
Calling a REST API or other web service API
As a developer using a REST API or other web service API, you don’t necessarily need to download anything. You can simply start sending requests over HTTP and receiving responses from the API, which does all the work on the server (“server side”). In some cases, however, the API developer or the development community supplies client libraries that developers can download to provide the basis for their app’s interactions with the API. Examples are the Flickr client library for .NET, the Twilio client libraries, and the client libraries for the Google Maps web services.
Importing a library-based API
For an Android API, you install the Android SDK and then add any additional SDK packages into your development project, within your IDE. (An IDE is an integrated development environment, such as Eclipse or IntelliJ IDEA.) In this case, the API download happens when the developer builds their application. See the Android documentation on installing the SDK and additional packages. The Google Maps Android API, for example, is one of a number of APIs distributed via the Google Play Services SDK, which is one of the packages described in the above link.
Downloading a flower
Recently encountered in my neighbourhood: This sulphur-crested cockatoo is importing a flower recently downloaded from a bottlebrush tree. 🙂
I’m very excited, because there’s an Android app on its way for Tech Comm on a Map. The Android app uses the same data source as the Tech Comm on a Map website – so you can see the same events on the map in both apps. In addition, you can add events to the map directly from within the Android app, and it does smart marker clustering too.
Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s already out there on the Web. See it in action on the Tech Comm on a Map website, and read more on this page.
And now the Android app
The code for the Android app is already on GitHub. A group of us got together during a hackathon and created the initial version of the app. I’ve added to the app since then, and intend to continue improving it. Eventually I’d like to add it to the Google Play store. There’s a bit to do before that. 🙂
Friendly disclaimer: Although I work at Google, this app is not a Google product. It’s a personal project by me and the other contributors.
The Tech Comm on a Map app for Android is developed with Java and the Android SDK. It uses the following APIs:
- Google Maps Android API
- Google Places API for Android (Autocomplete and Place Picker)
- Google Play services Fused Location Provider (Get Current Location)
- Google Apps Script
- Realm.io (a mobile database)
- AndroidSlidingUpPanel (a draggable sliding-up panel)
- Android Saripaar (a validation library):
If you’re interested in developments, follow the Tech Comm on a Map app for Android on GitHub. You can build it from the source and load it onto your Android device to try it out. It works. 🙂
Technical writers often need to create sample code, to illustrate the primary use case of an API or developer tool, and to help developers get started quickly in the use of the API or tool. Here are some tips on how to go about creating that code. I’ve jotted down everything I can think of. If you have more tips to add, please do. 🙂
I recently published a set of documentation on a utility library created by Chris Broadfoot, a Google developer programs engineer. The utility library is an adjunct to the Google Maps Android API. The documentation includes an overview of all the utilities in the library, a setup guide, and an in-depth guide to one of the utilities. (I’ll document more of the utilities as time goes on.) As part of the guide to the marker clustering utility, I created some sample code that illustrates the most basic usage of the utility and gets developers up and running fast.
Quick introduction to the API and the utility library
The Google Maps Android API is for developers who want to add a map to their Android apps. The API draws its data from the Google Maps database, handles the displaying of the map, and responds to gestures made by the user, such as zooming in and out of the map. You can also call API methods to add markers, rectangles and other polygons, segmented lines (called polylines), images (called ground overlays) and replacement map tiles (called tile overlays). It’s all in the API documentation.
The utility library is an extra set of code that developers can include in their Android apps. It includes a number of useful features that extend the base API. One of those features is “marker clustering”. The full list of features is in the utility library documentation.
The marker clustering utility
The sample code illustrates the marker clustering utility in Chris’s utility library. So before diving into the code, you be asking:
What’s “marker clustering”?
Let’s assume you have a map with a large number of markers. (Typically on a Google Map, a marker is one of those orange pointy droplets that marks a place on the map.) If you display all the markers at once and individually, the map looks ugly and is hard to grok, especially when the map is zoomed out and many markers are concentrated in a small area. One solution is to group neighbouring markers together into a single marker icon (a “cluster”) and then split them into individual marker icons when the user zooms out or clicks on the cluster icon. That’s what Chris‘s marker clustering utility does.
What does marker clustering look like? See the screenshots in the documentation.
Developers can implement the classes Chris has created and customise the appearance and behaviour of the clusters. The utility library also includes a demo app, containing sample implementations of the utilities.
The sample code
The best way to describe a code library is to provide sample code. I created a simple marker clustering example, based on the demo app. Take a look at the sample code in the documentation section on adding a simple marker clusterer.
Now compare it to the code in the demo app that’s part of the utility library: ClusteringDemoActivity.java
The differences, in a nutshell:
- The sample code doesn’t show any of the “plumbing”, such as the library import statements.
- The sample code does include a listing of both the primary method that does the clustering (called “
setUpClusterer()“) and a class that’s important for developers to understand (“
public class MyItem implements ClusterItem“).
- Instead of reading input from a file, the sample code includes a method called “
addItems()” to set up some sample data directly from within the code.
- I’ve added plentiful comments to the sample code, explaining the bits that are specific to marker clustering or the sample itself.
In summary, the sample code provides all the developer needs to get a simple marker clusterer working, just by copying and pasting the code into an existing Android project.
How to write sample code
While writing the sample code, a thought struck me:
Hey, it’s actually quite an interesting process writing sample code. I’ll blog about what I’m doing here, and see what other technical writers have to say about it. 🙂
First, a stab at defining the goals for the sample code:
- Get the developer up and running as quickly as possible.
- Be suitable for copying and pasting.
- Work (do what it’s meant to do) when dropped into a development project.
- Be as simple as clear as possible.
- Provide information that is not easy to find by reading the code.
- Illustrate the primary, basic use case of the API or tool.
And here are my jottings on how to go about creating a useful code sample:
- Find out what the primary and simplest use case is. That is what your code should illustrate. Talk to the engineers and product managers, read the requirements or design document, read the code comments.
- Find out what you can safely assume about your audience. Can you assume they are familiar with the technology you’re working with (in my case, Java and Android development)? Do you know which development tools they are using?
- Find some “real” code that does something similar to what you need. Perhaps a similar function or a working implementation that’s too complex for your needs.
- Simplify it. Make names more meaningful. Remove functionality that’s unique to your environment or that adds super-duper but superfluous features. Remove plumbing such as import statements and all but the essential error handling.
- Put your into a framework and test it. The framework should be one that your audience will be using. In my case, that’s an Android development project.
- Take screenshots of the code in action. They’re often useful to give people an idea of the goal of the sample code, and of what the API or tool can do.
- Get the code reviewed.
- Include it in the doc.
- If possible, put the code in a source repository and hook it up to some automated tests, to help ensure it will remain current.
- As far as possible, have all the necessary code in one piece, so that people can copy and paste easily. This may mean moving stuff around.
- Add code comments. Engineers often add technical comments to the code, but don’t include an introduction or conceptual overview of what’s going on. And our target audience, developers, will often read code comments where they don’t read other docs. So code comments are a great medium for technical communication!
Perhaps the most important thing to do is to see yourself as the advocate for or representative of those developers who need to use the API or tool you’re illustrating. Think what questions they would ask if they had access to the people and tools that you do, and put the answers into the documentation and sample code.
To do this job, tech writers need a certain level of coding knowledge, and also a good understanding of what a developer needs to get started. The sample code provides a stepping stone between the conceptual overviews and the complex implementations.
Well, that’s all I can think of. What have I forgotten? 🙂