Although I don’t work in road ecology or traffic engineering, the author somehow pulled me through 300 pages on this topic. He managed this not just through vivid language and diction, but by personally visiting places and telling stories about the specific challenges that animals, “carers,” forest service workers, and others faced as freeways and highways bisected and dissected their environments.
To use an analogy, suppose you’re a barista making espresso coffee. An AGI-capable robot trained as a barista is able to make all the coffee that a regular barista can make but twice as fast. Further, the Android barista can create exquisite espresso art in any shape that humans request, wowing them and making the experience novel. Soon the human barista is replaced. After all, the paying customer would rather pay $2.50 for a robot to make a latte instead of $5.00, especially when it tastes the same.
Most code samples in documentation are fairly basic, which is by design. Documentation tries to show the most common use of the API, not advanced scenarios for an enterprise-grade app whose complexity would easily overwhelm developers. (At that point, you end up with a sample app.)
With AI tools built directly into your authoring tool or IDE (such as VS Code), fixing simple doc bugs can become a mechanical, click-button task. Here’s the approach to fixing simple doc bugs:
(Note: The fact that I’m writing a book review on this topic might seem odd given that I usually focus on tech comm topics. However, I document APIs for getting map data into cars, so I sometimes read books related to the automotive and transportation domain. I also run a book club at work focused on these books.)
During the past few weeks, I’ve felt like my brain’s RPMs have been in the red zone. Granted, the constant stream of chaotic political news hasn’t helped—but regardless of current political events, I’m frequently checking the news, my email, and chat messages and operating in a mode that isn’t great. Reading long-form books has proven to be difficult. I run a book club at work focused on automotive and transportation books, and it took me two months to make it through a single book (granted, it was a 300-page historically dense book, but still).
“Biohacking” might be a pretentious cyber term for what is otherwise a straightforward experiment. For 10 days, I tracked my food and exercise levels while also wearing a continuous glucose monitor (CGM) to track my glucose levels. I then used AI to pair up the food + exercise with the glucose readings and perform an analysis about triggers for glucose spikes and recommendations to avoid them.
I want you to act as my AI stream journal (similar to a bullet journal), for the day. In this chat session, I’ll log 3 kinds of notes: tasks, thoughts, and events. Tasks are to-do list items. Thoughts are random ideas or notes I have. Events consist of food eaten, exercise, or descriptions of my internal states. The point is to have an easy way to dump all the scattered information in my head into a central log that you organize and analyze on my behalf.
In this Flickr API example, we want to get all the photos from a specific Flickr gallery called Color in Nature and display them on a web page. Here’s the gallery we want:
To achieve our goal, we’ll need to call several endpoints. Hopefully, this activity will demonstrate the shortcomings of just having reference documentation. When one endpoint requires another endpoint response as an input, you might have to communicate these workflows through tutorials.
1. Get an API key to make requests
Before you can make a request with the Flickr API, you’ll need an API key, which you can read more about here. When you register an app, you’re given a key and secret.
One of the arguments we need for the getPhotos endpoint is the gallery_id. Before we can get the gallery_id, however, we have to use another endpoint to retrieve it. Somewhat unintuitively, the gallery_id is not the ID that appears in the URL of the gallery.
Instead, we use the flickr.urls.lookupGallery endpoint listed in the URLs resource section to get the gallery_id from a gallery URL:
We can make the request to get the list of photos for this specific gallery_id.
Flickr provides an API Explorer to simplify calls to the endpoints. If we go to the API Explorer for the galleries.getPhotos endpoint, we can plug in the gallery_id and see the response, as well as get the URL syntax for the endpoint.
Insert the gallery_id, select JSON for the output, select Do not sign call (we’re just testing here, so we don’t need extra security), and then click Call Method.
Here’s the result:
The URL below the response shows the right syntax for using this method:
If you submit the request directly in your browser using the given URL, you can see the same response but in the browser rather than the API Explorer:
I’m using the JSON Formatting extension for Chrome to make the JSON response more readable. Without this plugin, the JSON response is compressed.
4. Analyze the response
All the necessary information is included in this response in order to display photos on our site, but it’s not entirely intuitive how we construct the image source URLs from the response.
In other words, the information a user needs to achieve a goal isn’t explicit in the API reference documentation. The reference docs explain only what’s returned in the response, not how to actually use the response.
You can construct the source URL to a photo once you know its ID, server ID, farm ID, and secret, as returned by many API methods.
The URL takes the following format:
https://farm{farm-id}.staticflickr.com/{server-id}/{id}_{secret}.jpg
or
https://farm{farm-id}.staticflickr.com/{server-id}/{id}_{secret}_[mstzb].jpg
or
https://farm{farm-id}.staticflickr.com/{server-id}/{id}_{o-secret}_o.(jpg|gif|png)
Here’s what an item in the JSON response looks like:
In this code, the ajax method from jQuery gets the JSON payload. The payload is assigned to the data argument and then logged to the console.
The data object contains an object called photos, which contains an array called photo. The title field is a property in an object in the photo array. The title is accessed through this dot notation: data.photos.photo[0].title.
To get each item in the object, jQuery’s each method loops through an object’s properties. Note that jQuery each method is commonly used for looping through results to get values. For the first argument (data.photos.photo), you identify the object that you want to access. For the function( i, gp ) arguments, you list an index and value. You can use any names you want here. gp becomes a variable that refers to the data.photos.photo object you’re looping through. i refers to the starting point through the object. (You don’t need to refer to i beyond the instance here unless you want to begin or end the loop at a certain point.)
To access the properties in the JSON object, we use gp.farm instead of data.photos.photo[0].farm, because gp is an object reference to data.photos.photo[i].
After the each function iterates through the response, I added some variables to make it easier to work with these components (using serverId instead of gp.server, etc.). And a console.log message checks to ensure we’re getting values for each of the elements we need.
This comment shows where we need to plug in each of the variables:
A common pattern in programming is to loop through a response. This code example used the each method from jQuery to look through all the items in the response and do something with each item. Sometimes you incorporate logic that loops through items and looks for certain conditions present to decide whether to take some action. Pay attention to methods for looping, as they are common scenarios in programming.
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
