Author Archives: Sarah Maddox
Many technical writers do other types of writing too. This week I had the pleasure and privilege of meeting one of them in person. Cynthia Chin-Lee is a manager in information development at Oracle, and also the author of a number of books. She made me a present of two of them – such a generous gesture.
One of the books Cynthia gave me is Amelia to Zora, Twenty-Six Women Who Changed the World. Cynthia is the author, and the illustrations are by Megan Halsey and Sean Addy.
Each page is about a woman who’s done amazing, beautiful, world-changing things with her life. Cynthia has managed to pack an enormous amount into just a few words about each person, with a quotation from each one. The illustrations by Megan and Sean are unusual and lovely. My favourite is the page about Imogen Cunningham, a photographer:
The second book Cynthia gave me is Operation Marriage, a story about a family of four: two mothers and two children. The mothers are gay, and at the start of the book they haven’t yet married. When they first decided to commit their lives to each other, marriage of gay couples was not legal in their part of the world. The story tells how their two children get together to persuade them to marry.
Cynthia Chin-Lee is the author and Lea Lyon is the illustrator.
The story is sensitively and neatly told, and the illustrations are just gorgeous. This is my favourite page, showing the family settled down on the couch to watch a video of the mothers’ commitment ceremony:
You can find details of the books on Cynthia’s website. Thank you Cynthia for a thoughtful gift.
To communicate with a REST API (or other web service API), you need to construct a request, send it over HTTP or HTTPS, then receive and parse the response. When creating an app, you do all that with code. But what if you just want to take a look around the API to see what it offers, before diving into the code? API explorers are your friend.
I’ve been putting together some information for a workshop on API technical writing. It’s been a rewarding exercise, because it’s made me think in a structured, educational way about what I do every day. A section of the workshop deals with various online API explorers that I’ve discovered over an extended period of time. This information is likely to be useful to many people, so I’m sharing it in a blog post.
API explorers offer a handy GUI alternative to a command-line tool like cURL. This blog post introduces the Advanced REST Client, which is a generic GUI for interacting with any REST API, and a few API explorers that interact with specific APIs.
Advanced REST Client
The Advanced REST Client is an add-on for Chrome browser. I find it very useful for sending a request to a REST API and receiving the response.
The Advanced REST Client offers a generic web form that you can use to craft an HTTP request, submit the request, and see the response. The screenshot below shows the Advanced REST Client in a Chrome tab. The top text box contains a request for the Flickr REST API. You can see the URL path and the URL parameters specifying the options needed for this particular request: the method (get public photos), the user ID of the person whose photos you want, and an API key.
(Click the image to see a larger version.)
Explorers for specific APIs
Developers of REST APIs and other web service APIs sometimes offer an API explorer, which people can use to take a look around the API before diving into the code.
The principle is the same as the Advanced REST client: an API explorer provides an online form where you can enter the parameters required for an API request, submit the request, and see the results.
The difference is that an API explorer is written for a specific API, whereas the Advanced REST Client is generic. The explorer therefore knows more about the API that it’s accessing. It can therefore:
- Present specific input boxes for the expected URL parameters and the input data expected in the request body.
- Hide such pesky complexities as user authentication. In many cases, you can sign in as a user of the web service, and the API explorer will create any authentication tokens that you need.
Flickr REST API Explorer
To see Flickr’s API explorer in action, you can experiment with requesting a user’s public photos from Flickr. Follow these steps to use the
flickr.people.getPublicPhotos method in the API explorer:
- Go to this link in your browser: https://www.flickr.com/services/api/explore/flickr.people.getPublicPhotos
You should see Flickr’s App Garden, showing a form with input fields for the arguments required in the request for public photos.
- Enter the following values:
- user_id: Paste in the Flickr user ID of the user whose public photos you wish to retrieve. A user ID is a string of characters with an @ sign in the middle. For example, use your own Flickr user ID or feel free to use mine: 31065906@N08.
- Leave all the optional arguments empty.
- Output: Select XML (REST). This is the default option.
- Authentication: Select Do not sign call. (Flickr does not require authentication for this particular API request.)
- Click Call Method.
- Scroll down to see the response. The API explorer returns the response body, and a copy of the request URL.
This screenshot shows the input fields for the
To find all the methods available in Flickr’s API explorer, go to this web page: https://www.flickr.com/services/api/
The methods are listed down the right-hand side of the page. For example, to find the method you’ve used earlier:
- Click the link on the words flickr.people.getPublicPhotos. You’ll see a documentation page about the getPublicPhotos method.
- Scroll to the bottom, and click the link to the API Explorer for the method.
Twitter REST API Explorer
Twitter’s REST API requires user authentication for every request. The API explorer is especially useful in this case, because it takes care of the authentication plumbing for you. All you need to do is give the explorer permission to access Twitter’s data via your Twitter username. Twitter uses the OAuth 1.0 protocol to authenticate the user. In this case, you’re the user, because you’re using the API explorer. This will all become clear if you follow the steps below. :)
- Go to the Twitter website and sign in as usual. (You do need a Twitter account to try this exercise.)
- Go to the Twitter API explorer at Exploring the Twitter API.
- Click the dropdown arrow under Authentication and select OAuth 1.
- A popup window appears, titled Request Twitter permissions. If you can’t see it, scroll down the page a bit.
- Click Sign in with Twitter.
- A window appears, titled Authorize Apigee’s API Console to use your account?
- Click Authorize app.
- You should see a short-lived message saying that you’ll be redirected back to the app. Then you’ll find yourself back in the Twitter API explorer. Under Authentication, you’ll see Twitter-<username> where <username> is your Twitter handle. For example, for me it shows “Twitter-sarahmaddox”.
- Under Select an API method, you’ll see a list of methods – these are the things you can do with the API. Click /statuses/user_timeline.json in the first set of methods (next to one of the blue “GET” buttons).
- A new set of panels appears. In the Query panel (the smallish panel near the top of the window), scroll down until you can see the user_id and screen_name fields. They’re right at the bottom of the panel, and not immediately visible. In the screenshot below, I’ve already scrolled down within the Query panel.
- Enter a Twitter username and screen name. In this screenshot, I’ve entered my own Twitter ID:
- Click Send. (The red button near top right.)
- A short-lived red-flashing message appears, letting you know the app is working. Then the response appears. If you see a green 200 OK, that means everything went well.
- Scroll down to see the full response. It’s in JSON format. The top part of it looks like this (but there’s much more):
Various Google APIs
The Google APIs Explorer provides a GUI interface for many of the Google APIs, including the Calendar API, the Gmail API, and many more:
Tech Comm on a Map now has a category for educational programs and courses, such as university technical communication degrees or certificates and other training courses. Take a look and let me know if you have something to add.
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 a great way of seeing what we tech writers are up to, around the world. To find out more about the project, or to add something to the map, check out the project information page.
The STC (Society for Technical Communication) is presenting a series of webinars (online seminars) on API technical writing, starting in February. I’m delighted to be presenting the first webinar in the series: Part 1: Introduction to API Technical Writing.
The role of API technical writer is exciting, rewarding, and challenging. In this webinar we’ll explore what an API is and does, see a couple of APIs in action (provided the demo gremlins stay away!), take a look at some examples of API documentation, and hear some tips on getting started in the role.
Details of the first webinar in the series
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am here in Sydney!
Duration: One hour.
Fees and registration details: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.
Here’s an outline of the session:
- Introduction to the role of API technical writer
- Overview of the types of developer products we may be asked to document
- What an API is and who uses it
- A couple of live demos of APIs that you can play with at home
- Examples of good API documentation
- The components of API documentation, and the technical writer’s role in the creation of each component
- Tips on getting started as an API technical writer
Focus on APIs in the world of technical documentation
APIs are a hot topic in our field. Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.
Then there’s my upcoming API workshop in January (now fully subscribed) sponsored by the STC and Google. Tom Johnson runs an API workshop at TC Camp 2015. The September edition of Intercom focused on API technical writing. Tom Johnson has written some truly excellent blog posts on the subject over the last few months, the latest of which is a podcast with Joe Malin. Here’s a list of my own posts about APIs.
Are you into, or interested in, API tech writing?
Phew, a hot topic indeed. I’d love to know whether it’s something you’re interested in. Perhaps you’re dabbling in APIs, or already into them full time?
I’m excited and delighted to announce that I’ll be presenting a one-day workshop on API technical writing, in conjunction with the Silicon Valley Chapter of the STC (Society for Technical Communication).
The workshop will be a practical course on API technical writing, consisting of lectures interspersed with hands-on sessions where you’ll apply what you’ve learned. The focus will be on APIs themselves as well as on documentation, since technical writers need to be able to understand and use a product before we can document it.
Date: Friday, January 23rd, 2015
Time: 9 am to 4 pm
Location: 1295 Charleston Rd, Mountain View, CA 94043 (Google Maps: https://goo.gl/maps/yW1hu). The building is on the Google campus. The workshop takes place in the “Araujo Tech Talk” room on level 1.
Cost: None. The course is given free of charge, sponsored by Google and the STC Silicon Valley Chapter.
- STC membership is not required.
- The course is currently fully subscribed. But it’s worth adding your name to the waiting list, in case a place becomes available closer to the date. We’ll check the number of tickets and the waiting list early in January.
- If you’ve registered but later find you’re unable to attend, you can cancel your order in EventBrite. This will open up a place for people who are on the waiting list.
The course will include the following sessions:
- Lecture: The components of API documentation.
- Hands-on: Generate reference documentation using Javadoc.
- Lecture: Beyond Javadoc – other doc generation tools.
Details and signup
For details of food, what to bring, prerequisites, and how to sign up via EventBrite, please head on over to the STC Silicon Valley workshop page.
Here’s some information about parking near 1295 Charleston Rd, Mountain View (Google Maps: https://goo.gl/maps/yW1hu):
- There are several parking lots next to building 1295. You can park in any unmarked spot. Avoid spots that are marked for expectant mothers or other special requirements.
- If parking immediately near building 1295 is full, you can park in the lots near building SB50 (1350 Shorebird Way):
- You can also make use of the valet parking between 1245 & 1225 Charleston Rd.
Questions and comments
Please let me know if you have any questions or comments.