Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

API Workshop: Deep dive into REST APIs


Published on

These slides focus on documentation for REST APIs. See for more detail. For the video recording, see This deep dive is the second slide deck I used in the presentation.

Published in: Technology
  • ⇒ ⇐ This service will write as best as they can. So you do not need to waste the time on rewritings.
    Are you sure you want to  Yes  No
    Your message goes here

API Workshop: Deep dive into REST APIs

  1. 1. API Documentation Workshop: Deep Dive into REST APIs By Tom Johnson January 24, 2015
  2. 2. REST • Client-server architecture: You send a request and get a response back. REST is the model of the web. REST APIs also called “web APIs.” • REST = “representational state transfer” – data transfer modeled after the web. • Protocol transfer is HTTP. Requests are made through URLs. • Can see the response in the browser. • Responses are stateless -- not remembered.
  3. 3. Sample endpoints{apikey}/users // gets all users{apikey}/users/{userId} // gets a specific user{apikey}/rewards // gets all rewards{apikey}/rewards/{rewardId} // gets a specific reward{apikey}/users/{userId}/rewards // gets all rewards for a specific user{apikey}/users/{userId}/rewards/{rewardId} // gets a specific reward for a specific user In a well-designed API, you can predict the logic of the requests. A “RESTful web service” has “endpoints” that return “resources.”
  4. 4. Responses (usually JSON) { "user”:"1234", "userName":"Tom", "userCreatedDate":"09021975", ”userStatus: "active" } A JSON object consists of key: value pairs.
  5. 5. Some objects contain lists of items in brackets [ ]. Here the photo object contains an array.
  6. 6. Get familiar w/ the Developer Console
  7. 7. Console.log In code samples, you can use console.log(data) to log an object called “data” to the console. Then “inspect the payload.”
  8. 8. HTTP requests have methods GET POST DELETE PUT The methods available for each resource differ. DELETE methods aren’t usually passed in regular web page code for security reasons. Usually only submitted using cURL.
  9. 9. Look on the Network tab of your console when you make a web request, and you can see the method for each request.
  10. 10. Activity 1. Open the JavaScript Console and go to the Network Tab. 2. Browse to your favorite website (e.g., 3. Look at the requests and responses logged in the Network tab.
  12. 12. EventBrite API example Let’s get some event details using the events endpoint from the EventBrite API.
  13. 13. Get eventbrite event details Endpoint:{event_id} Endpoint with values: ?token=C4QTJZP64YS5ITN4JSPM Response: { "resource_uri": "", "name": { "text": "API Workshop with Sarah Maddox", }, "description": { "text": "This is a practical course on API technical writing, consisting of… BTW, the API key values on my slides are fake.
  14. 14. <html><body> <script type='text/javascript' src="// uery.min.js"></script> <script> var url = " /?token=C4QTGZP64YS5ITN4JSPM"; $.getJSON( url, function( data ) { console.log(data); var content = "<h2>" + + "</h2>" + data.description.html; $("#eventbrite").append(content); }); </script> <div id="eventbrite"></div> </body></html> A simple way to display the response on the page.
  15. 15. Open your console and inspect the payload that is logged to the console via console.log in the code.
  16. 16. Accessing JSON using dot notation To get the values from the json, use dot notation. If our object is named data, then gets that value.
  17. 17. Activity 1. Open the JavaScript Console and go to the Console tab. 2. Open the eventbrite.html file in your browser. 3. Inspect the payload.
  18. 18. Code samples should be simple - Focus on call and response. What’s important is the endpoint, its parameters, and the resource it returns. - No styling. In code samples, don’t get complicated with styling unless you’re providing a copy-and-paste widget. The more you strip away, the better. Analogy with graphics.
  19. 19. Common sections in REST API doc • Resource (“endpoint”) • Description • Parameters • Methods • Response • Example • Error codes Cover these details for each resource in your REST API docs. Click thumbnail for example.
  20. 20. Example: Get Klout Score Klout has an interactive console.
  21. 21. Get klout score Endpoint: user.json/{kloutid}/score Endpoint with values: ?key=urgey4a79njk6df6xx4p64dr Response: { "score": 92.2655186160279, "scoreDelta": { "dayChange": 0.00044535591406713593, ... } We have to call another resource first to get the Klout ID.
  22. 22. Get Klout ID from Twitter handle Endpoint: identity.json/twitter?screenName={username} Endpoint with values: creenName=tomjohnson&key=urgeykj79n5x6df6xx4p64 dr Response: { "id": "1134760", "network": "ks" }
  23. 23. <html> <body> <script src=" 1.11.1/jquery.min.js"></script> <script> var url = " key=urgey4a79n5x6df6xx4p64dr&callback=?"; $.getJSON( url, function( data ) { console.log(data.score); $("#kloutScore").append(data.score); }); </script> <h2>My Klout Score</h2> <div id="kloutScore"/></body></html> Tip: jQuery makes life a lot simpler.
  24. 24. Here’s the result:
  25. 25. Get Klout Score using PHP Use whatever language you want to implement the web API calls.
  26. 26. Get Klout Score using Python This is why providing code samples can be problematic. Where do you stop? Ruby, Java, Node, Python, JavaScript?
  27. 27. Activity: Get your Klout score 1. Go to 2. Use the identity endpoint to get your Klout ID based on your Twitter name. 3. Use the score endpoint to get your score. For API key, you can use the key in the apicalls.txt file or sign up for your own.
  28. 28. Example: Get influencees BTW, reference docs don’t tell you all you need to know. For example, what are influencers and influencees?
  29. 29. Get klout influencees Endpoint: user.json/{kloutid}/influence Endpoint with values: ence?key=urgerjy4a79n5x6df6xx4p64dr Response: { "score": 92.2655186160279, "scoreDelta": { "dayChange": 0.00044535591406713593, ... } API keys regulate usage and prevent servers from abuse by too many calls.
  30. 30. <html><body> <script src=" /jquery.min.js"></script> <script> var url = " y=u4r7nd397bj9ksxfx3cuy6hw&callback=?"; $.getJSON( url, function( data ) { console.log(data); $.each( data.myInfluencees, function( i, inf ) { $("#kloutInf").append('<li><a href="'+inf.entity.payload.nick + '">' + inf.entity.payload.nick + '</a></li>'); }); }); </script> <h2>My influencees</h2> jQuery’s each method can iterate through items in an array.
  31. 31. Activity 1. Open the klout-influence.html file. 2. Identify the endpoint used in the code. 3. Replace the user ID with your own user ID. 4. Paste the endpoint into your browser and identify your influencers.
  32. 32. Flickr Example: Get gallery photos
  33. 33. Get flickr photo gallery Endpoint: flickr.galleries.getPhotos Endpoint with values: ickr.galleries.getPhotos&api_key=c962d7440cbbf3 81785c09989ba8032e&gallery_id=66911286- 72157647277042064&format=json&nojsoncallback=1 Response: { "score": 92.2655186160279, "scoreDelta": { "dayChange": 0.00044535591406713593, … }
  34. 34. Activity 1. Open the flickr.html file in a text editor. 2. Copy the endpoint (url) and paste it into your browser. 3. Try to find the image source URLs in the payload.
  35. 35. $("#flickr").append('<img src="https://farm' + farmId + '' + serverId + '/' + id + '_' + secret + '.jpg"/>'); API reference docs don’t tell you how to actually do a real task. To construct the img URL, you need to combine 4 different parts from the response.
  36. 36. Flickr Result
  37. 37. More details on the API calls Go here for details:
  39. 39. Sample REST API doc sites Many API doc sites are modern looking and awesome. Remember, the API Doc is the product interface, so it has to look good.
  40. 40. API Directory 12,000 + web APIs
  41. 41. What design trends or patterns do we see among popular API doc sites?
  42. 42. Stripe API Code responses next to doc.
  43. 43. Single page scroll w/ TOC highlight Third column to show responses or code samples.
  44. 44. Jekyll API doc theme from CloudCannon
  45. 45. Bootstrap scollspy demo
  46. 46. Yelp API One seamless website matching product branding.
  47. 47. Twilio API One output, with nav tabs to show different languages
  48. 48. Twitter API Interactive, real- time requests based on your auth key
  49. 49. Dynamically inserted API keys into code samples.
  50. 50. Foursquare API Often begin with Getting Started section, providing a sample “Hello World” tutorial
  51. 51. Youtube API Lots of code samples, usually with syntax highlighting and surrounding commentary.
  52. 52. 8 design trends with API doc 1. Third column to show responses & code 2. Single page scroll with scrollspy TOC highlight and floating sidebar 3. Seamless website matching product branding 4. Nav tabs to show different code samples 5. Code syntax highlighting 6. Hello World getting started section 7. Interactive, personalized API explorer 8. Static site generators that process Markdown syntax
  53. 53. Some non-trends 1. PDF output 2. Short pages 3. Multiple (highly duplicate) outputs of content for different audiences 4. DITA or XML authoring models 5. EPUB formats 6. Comments on pages 7. Wikis 8. Video tutorials
  54. 54. Question: How do tech writers make beautiful API doc websites?
  55. 55. How do you merge worlds?
  56. 56. TOC dynamically generated and highlights based on position. My Jekyll Prototype
  58. 58. Auto-generated reference doc solutions • Swagger • RAML • Enunciate • API Blueprint • Mashery I/O • Miredot (Java only) •
  59. 59. Most common automated options “Github stats (with caveat: these are repos, do not necessarily all represent implementations): Swagger: 600+ repos (270+ JS, 80+ Java, 31 Python) RAML: 180+ repos (54 JS, 21 Java, nothing listed for Python) I/O Docs: 30-40 repos (mostly JS, some Java) API Blueprint: 120+ repos (again, mostly JS, some Java, some Python)” – slide notes from Jennifer Rondeau presentation on REST API Doc
  60. 60. What is Swagger? A spec for describing an API so that humans and computers and read and explore it. Different tools can parse the Swagger spec and render different outputs. “The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.” – Swagger UI project See Swagger spec here:
  61. 61. Swagger is just a standard way of describing your API using a particular JSON schema.
  62. 62. Use Swagger Editor to avoid syntax errors
  63. 63. Swagger UI’s output
  64. 64. Swagger basics • Swagger is a spec, a JSON schema for describing your API in a standard way that tools can process. (Kind of like DITA.) • “Swagger UI” is one tool that parses the Swagger spec from a JSON file. With this approach, the JSON file is separate from the source. • There are also many Swagger libraries that integrate directly into API source code.
  65. 65. Activity 1. Go to 2. File > Open Example > Pet Store Simple. 3. Mode > Editor. Make some simple changes, including host value. 4. File > Download JSON. 5. Download Swagger-UI. api/swagger-ui 6. In dist folder, open index.html, change url value. 7. Upload to web server and try it out. Try content/apidemos/swagger/dist.
  66. 66. RAML basics • Stands for REST API Modeling Language. • Similar to Swagger, RAML is a competing spec for describing APIs in a way that tools can parse. • Arrived later on the scene after Swagger, but seems smarter and more efficient. • RAML parsers built into comprehensive API platform tooling from Mulesoft.
  67. 67. Sample RAML code RAML’s JSON is more human readable than Swagger.
  68. 68. Mulesoft’s Anypoint platform workflow 1. Design in online editor called API Designer. 2. Publish an API portal for users to view.
  69. 69. API Designer for RAML From Mulesoft: “Write human-readable, markdown-formatted descriptions throughout your RAML spec, or include entire markdown documentation sections at the root.”
  70. 70. Keep descriptions short, link elsewhere The doc in the interactive console is more like a quick reference guide. But this creates organizational challenges for content.
  71. 71. Sample API Portal from RAML spec
  72. 72. RAML API Console output (Mulesoft) Here’s a more robust example. Instead of expanding the details, the details appear in a modal overlay.
  73. 73. Swagger vs. RAML • Swagger was first on the block, has more community, street recognition. • Swagger’s spec is more complicated, learning curve higher. • Swagger uses JSON. RAML uses YML. • RAML is more recent, has smaller user base. • RAML has thorough documentation & tutorials, but tooling seems less open.
  74. 74. Comparing specs swagger/ I included some sample Swagger & RAML files from this site for comparison.
  75. 75. Activity: Compare the specs 1. In the apiworkshop files, open the raml.yml and swagger.json files and compare the specs. 2. Go to and explore Swagger’s demo. 3. Go to http://api- and explore several API Consoles (e.g. Box). 4. Which experience do you like better?
  76. 76. Pros of automated doc • No doc drift. Documentation more in sync with doc. • More real. Data responses more meaningful & real to user because they’re based on actual user data. • Interactive. Gives interactive playground to documentation, encouraging user not just to read but to do, try, experiment, and play with API. • Sexy. Makes API doc snazzy and sexy. Your doc is the cool kid on the block. • Convenient. In-source location of doc provides convenience for engineers working with code.
  77. 77. Cons of automated output • Data anemic responses. Will users new to your API have rich enough data to populate the responses well? • Glorified API explorer. Not much different from an API Explorer. Not sure if all the fuss is worthwhile. • Poor integration. Automated outputs don’t often integrate well with non-reference documentation. Separate outputs. • Data damage risk. Potential risk of having user apply DELETE or UPDATE method and ruin actual content. • Engineers can’t write. Doc is often better when under the control of tech writers anyway. Engineers troubled by curse of knowledge. • Ref docs are an illusion. Reference doc gives you the “illusion” of having real doc. Makes you think other doc not needed. • Fail in complicated scenarios. Not useful for more complicated API scenarios, where you pass one endpoint’s result into another.
  78. 78. Recommended Resource
  79. 79. Tom Johnson @tomjohnson
  80. 80. Image credits • Slide 39: Catwoman. • Slide 41, 54: Finger face with question. By Tsahi Levent-Levi. • Slide 55: Nasa, new eyes: Butterfly.