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:
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.
This week I’m attending Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. I’m excited to be part of this event. I’ll blog about my take-aways from the sessions I attend, and anything else that comes to mind.
The keynote this morning was Being human in a digital world, by Genevieve Bell. The link is to my post about that funny, inspiring talk. Now for my notes on the rest of the day.
Elements of API excellence, by Jeremiah Lee
Jeremiah Lee is lead API engineer at Fitbit. His talk was about evaluating the maturity of APIs, and what it takes to make an excellent API.
Jeremiah ran through some scenarios that may result in a bad API. For example, you may create an API unintentionally (it was just something we auto-generated, and people started using it), selfishly (we looked only at our own requirements), or blindly (we imitated other APIs, without knowing why).
Instead, we need to actively understand the problem that needs to be solved, and to test it thoroughly before letting it loose in the wild. And we need to design it holistically. How? Tie up with our UX colleagues. We need to understand the people who use the code, as well as the code itself. The users of APIs are our peers – other engineers.
Empathy is an applied science. UX is a research-driven field. The aim is to acquire knowledge, with the purpose of doing something with that knowledge.
An excellent API is functional, reliable, secure, usable and pleasurable. Jeremiah broke down each of those points into smaller divisions. For example, usability breaks down into intuitability, testability, and corrective guidance. Pleasurable means that integrating the API is something you’d choose to do again.
Personas are a useful way of getting to know your users. Remember, in this case the users are other developers. Personas describe the people who use the product and the context they operate in. Personas also make visible our assumptions about users, and give our team a frame of reference. Jeremiah took us through the development of personas for API users, and the type of characteristics we’d need to analyse to create such personas. For example, what technologies are they using, what’s their skill level, and more.
Passive usability testing is the idea that we can use our existing data and systems to test the usability of our APIs. For example, the engineers can examine the support requests with specific questions in mind: at what times are people asking for help – immediately after a release or on long-running software; what are the frequently asked questions; what are the frequently misunderstood concepts; and so on. Another passive usability testing technique is to look at the data about API usage during an integration: how long between app registration and first request; what are the first requests and first errors; and so on.
Then there’s active usability testing. Go out and talk to people who are using the API. Hang out with them at their place of work, and take notes about how they use the API. See how they talk about the API with the rest of their team; how do they get started and what problems do they encounter/solve; how does the API fit in with the rest of their app? Or create a prototype of the API, and have people use it. Jeremiah recommends Silverback to record the user’s reaction, and then look at their emotional responses at various points during the integration. Were they happy or sad, and can we fix the sad moments.
Jeremiah finished by saying he hasn’t given us answers to building an excellent API, because there are no one-fits-all answers. Instead, he has given us the tools to find those answers.
Build better content, by Jonathon Colman
Jonathon Colman is a content strategist at Facebook. I’ve met Jonathon a couple of times, most recently at the STC Summit in Phoenix AZ earlier this year. It turns out we share the habit of waking up before the crack of dawn, and falling asleep soon after the birds stop tweeting for the day. We also share a love of technical writing. 🙂
Jonathan’s talk focused on how content strategy has to be part of UX strategy. He started off by promising us 127 slides! He’s a “madman with a clicker”. Heh. The slides are at bit.ly/fixourshit. Heh again.
First we looked at some definitions of content strategy. Then we saw some new Facebook content that aim to improve user experience, such as a privacy tool. It’s all about using language as an interface. Language is how we understand things. Content strategy is interaction design, because it focuses on experience, and the users of a product. Content strategy blurs the lines between engineering, design, testing, and so on. It crosses all those silos, focusing on the user. Jonathan calls this “intertwingling”.
The aim is to design content as a system, a product and an experience. Not as a campaign. Jonathan aligns his strategy with Lean principles: build, measure, learn. He also stresses the importance of incorporating your organisation’s core values into the design. And then go back and question your norms and values, especially if something breaks. Always remember that people are on the other end of the system.
“Slow down and fix your shit” – this is the essence of content strategy. Jonathan walked us through the quality framework his team uses at Facebook, and the content principles that guide them through the complex path of designing a product from strategy to the surface where the users see it. Aim for: simple, straightforward and human.
Thanks Jonathon for an information-packed session. Some quotes that made me think:
- Keep it simple, get to the point, and talk like a person
- Great content is invisible
- If you want a better Web, you have to build it
A voice for everyone, by Doug Bowman
Doug Bowman talked about his experiences as Creative Director at Twitter, and how products like Twitter are giving people a voice. If eyes are the window to the soul, then the voice is the gateway to the heart. Whether the voice is spoken or written. A voice can change your day, or alter your life for ever. But a voice can only be powerful if it’s heard.
Doug started working at Twitter five years ago, when there were no designers in the company. So he got to grow the designer team from scratch. He loves Twitter. It’s connected him to so many people that he hadn’t met before.
The message that Doug wants to share is the human connection. Twitter is unique and wonderful because of the people who use it, not because of the service. We can connect with anyone who shares an interest with us, whether we know them or not. We get to overhear the conversations between people we don’t know.
Doug read out some tweets from conference attendees, showing lots of humour and character. He also showed us some cute, funny tweets between people or businesses, famous and not. Where else do you see businesses taking the time to reply to random mentions of their name, and often in the same humorous vein? Then we looked at some more serious tweets among people mourning a loss or going through other difficult experiences.
Tweets are a series of human moments. But you can also analyse the tweets en masse, to see patterns. For example, the tweets mentioning #hungry spike at certain times of the day. How about the tag #tired – it’s the pulse of humanity. You can see when people tend to be happy, late for work, hung over…
Big events show a huge outpouring of emotion, such as when the Giants won the World Series, or shocking world events happen. Doug told us the story of Vivienne, who made a commitment to earn $100,000 to free 500 child slaves, by selling lemonade at a stand on her street for a year. That was 5 years ago, when she was 5 years old. Her father helped her tweet about it. She reached her goal in half the time planned. What’s more, she’s given a TED Talk and runs a company that aims to end child slavery.
These stories of human connection were rooted in Twitter. But Doug’s message is for everything we do. As communicators and designers, we are the creators of the modern age. It’s our responsibility to make sure everyone on this Earth has a voice.
Architecting the rise of connected devices, by Hadi Michael
Hadi Michael is a digital adviser and software engineer at Deloitte Digital. He gave the first of three 15-minute sessions. His talk is about the importance of API layers in the growth of the Internet of Things. An example of a connected device might be a chair. It could have sensors, activators, computational power, and connectivity. The powerful idea is that the devices have contextual awareness. Some devices may decide to activate when you leave the home, such as those that clean the house. Others may switch off when you leave. Cisco estimates that we’ll have 50 billion connected devices by 2020. And that’s a conservative estimate.
How are we going to handle this – how will our solution architectures service this growing number of connected devices? Hadi showed us how various organisations have started preparing. Those that are successful have API layers at the core of their architectures, either unifying their API layer retrospectively, or doing it right from the start. The trick is to move your business systems behind the API layer, at least when there’s any chance that you’ll want to expose those systems to anything other than just the website.
Hadi walked through some tips for designers when taking connected devices into account. Thanks for a tantalising glimpse into the world of connected design!
Welcome to the fold, by Katie Miller
Responsive in the wild, by Guy Podjarny
Guy Podjarny is Chief Technology Officer at Akamai. Guy’s talk was about the adoption of responsive web design. Which websites are going response, and how are we architecting them?
When we try to see if a website is responsive, we usually just resize the page and see if the content is cut off. We also look for a scrollbar, which indicates a non-responsive site. This isn’t ideal, but it’s pretty good and we can automate it. Guy showed us the details of the test he ran, and the results. Here are some highlights.
The adoption in the top 10,000 sites has grown by approx 8% over the last year. The average number of requests in responsive websites is substantially lower than non-responsive. The average resource size in the responsive websites is bigger. Interestingly, the image size is also bigger in responsive sites – perhaps because of retina?
Guy also compared responsive designs on the big screen with the small screen. We’d expect a substantially lower volume of data on the small screen. That’s not the pattern that shows up, presumably because the resources are downloaded anyway and then just hidden or shrunk on the client. Only approx 13% of responsive websites are 50%+ smaller on mobile. We’re doing better here than last year, but still need to make an effort.
Mobile-only sites are significantly smaller than responsive sites. Processing time follows the same pattern. Responsive sites take longer to process than mobile sites.
In summary: Adoption of responsive design has nearly doubled in less than a year. But we need to work on the performance.
Haunted machines, by Tobias Revell
Tobias Revell is a critical designer and futurist. He gave the closing keynote of the conference. Note: Today is 31 October. Halloween!
Tobias’s talk revolved around the notion that any sufficiently advanced technology is indistinguishable from magic. (From Arthur C Clarke.) Tobias gave some examples of recent hoaxes: that if you add this app to your phone, it will become waterproof, or that you can put your phone in a microwave oven to recharge it. The amazing thing is that people fell for these hoaxes. But the fact is that people are dealing with such advanced technology that they can’t understand it. As technology gets more and more advanced, it gets more and more opaque.
On the other hand, people have built computers on Minecraft. Some people are even trying to build a computer on Minecraft that you can play Minecraft on. Go figure.
Tobias gave us a link to his site: The Ongoing Collapse, “a growing collection of data sources and links positioned as a reflection of the state of the world in the terms that it likes to use. It’s a gentle ticking of the crumbling weird at the base of civilisation”. (More about the site.)
Tobias ended with this somewhat convoluted, dark thought: As makers of virtual reality, we control people’s perception of objective reality. Happy Halloween!
Thanks Tobias for a rollercoaster ride past ghosts and technologies past, present and future.