Download as PDF, PPTX
Uploaded bySarah Maddox
API Technical Writing
This document provides an introduction to API technical writing. It begins with definitions of APIs and their role in software development. It then discusses different types of APIs and provides demonstrations of JavaScript and REST APIs. The document outlines key components of API documentation and provides examples. It also discusses how API technical writers work with engineering teams and how to get started in the field.
In this document
Powered by AI
Overview of the presentation focusing on API Technical Writing, the role of an API writer, audience, and the structure of the content.
Definition of API, its purpose for app communication, types like REST, SOAP, and components like WSDL, and methods of interaction.
Responsibilities of an API technical writer include aiding developers, explaining concepts, and writing documentation.
The target audience for APIs comprises inventive developers across various platforms including web, mobile, and more.
Different types of APIs discussed including Library-based APIs, Web service APIs, and hardware APIs.
Demonstration of using Google Maps JavaScript API with sample code illustrating API integration.
Demonstration of calling the Flickr API, discussing HTTP requests, response structures, and types of requests.
Key components of API documentation like conceptual overviews, practical tutorials, automated documentation, and examples.
Examples of API documentation showcasing Google Maps JavaScript API, Twitter REST API, and Google Maps Android API.
The importance of working with engineering teams to gather information, advocate for developers, and enhance documentation.
Steps to start documenting APIs, learning, and continuous development in the API landscape, along with contact information.
More Related Content
Similar to API Technical Writing
API Technical Writing
- 1. tcworld India 2016 APITechnical Writing #APItechcomm @sarahmaddox Introduction to
- 2. contents #APItechcomm @sarahmaddox What isan API? Our role and audience API types Demos of two APIs Components of API documentation Examples of API documentation Working with an engineering team How to get started
- 3. contents #APItechcomm @sarahmaddox What isan API? Our role and audience API types Demos of two APIs Components of API documentation Examples of API documentation Working with an engineering team How to get started
- 4.
- 5. #APItechcomm @sarahmaddox Application ProgrammingInterface (API) A means of communication ● App to app ● Automated A description of the communication methods allowed ● Requesting information ● Sending information ● Updating information The mechanisms supporting those interactions A way for apps to exchange information with each otherWhat is an API?
- 6. #APItechcomm @sarahmaddox Usually notUI ○ Software-to-software interaction, not user interaction ○ May provide a UI widget “Components” rather than “apps”? ○ Yes, that’s more precise ○ But “app” is good for most purposes “APIs” = features within an API? ○ No, although fairly common usage ○ Those are classes, methods, endpoints, etc A way for apps to exchange information with each otherWhat is an API?
- 7. #APItechcomm @sarahmaddox The rules/ protocol ● Documentation ● WSDL ● WADL Code libraries What an app needs
- 8. #APItechcomm @sarahmaddox WWW URI orURL HTTP or HTTPS Web service APIs SOAP XML-RPC and JSON-RPC REST Web services REST APIs and more
- 9.
- 10.
- 11.
- 12. #APItechcomm @sarahmaddox <?xml version="1.0" encoding="utf-8"?> <GreyCloudAppResponse> <status>OK</status> <result> <type>greeting</type> <text>hello back</text> </result> </GreyCloudAppResponse>
- 13. #APItechcomm @sarahmaddox The roleof an API tech writer
- 14. #APItechcomm @sarahmaddox Explain concepts Showpeople how to do something Publish the terms of service of a product Notify people of changes and new features What does an API technical writer do? Help people complete a task or use a product
- 15. #APItechcomm @sarahmaddox What doesan API technical writer do? Advise developers on naming conventions Stand up for code readability Write sample code Write video scripts Present videos, workshops, webinars < else Opportunities for creativity as well as writing/coding zone
- 16. #APItechcomm @sarahmaddox <script type=‘text/javascript’> //Say hello world until the user starts questioning // the meaningfulness of their existence. function helloWorld(world) { for (var i = 42; i > 0; i--) { alert (‘Hello’ + String(world)); } } </script> You mean you spend your day on stuff like this?
- 17. #APItechcomm @sarahmaddox <script type=‘text/javascript’> //Say hello world until the user starts questioning // the meaningfulness of their existence. function helloWorld(world) { for (var i = 42; i > 0; i--) { alert (‘Hello’ + String(world)); } } </script> You mean you spend your day on stuff like this? ;-)
- 18. #APItechcomm @sarahmaddox Who’s ouraudience?
- 19.
- 20. #APItechcomm @sarahmaddox ● Displayyour Twitter stream on your Wordpress blog ● Add Flickr photos to Confluence wiki pages ● Embed YouTube videos all over the show APIs in the real world
- 21.
- 22. #APItechcomm @sarahmaddox Web serviceAPIs SOAP XML-RPC and JSON-RPC REST Library-based APIs JavaScript TWAIN Class-based APIs (object orientation) Java API Android API OS functions and routines Access to file system Access to user interface Object remoting APIs CORBA .NET Remoting Hardware APIs Video accelerators Cameras A classification of APIs
- 23.
- 24. #APItechcomm @sarahmaddox Demo ofa JavaScript API
- 25.
- 26. #APItechcomm @sarahmaddox <!DOCTYPE html> <html> <head> <styletype="text/css"> html, body { height: 100%; margin: 0; padding: 0; } #map { height: 100%; } </style> </head> <body> <div id="map"></div> <script type="text/javascript"> var map; function initMap() { map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.857, lng: 151.215}, zoom: 13 }); } </script> <script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR-API-KEY&callback=initMap"> </script> </body> </html> Google Maps JavaScript API
- 27. #APItechcomm @sarahmaddox <head> <style type="text/css"> html,body { height: 100%; margin: 0; padding: 0; } #map { height: 100%; } </style> </head> Google Maps JavaScript API
- 28. #APItechcomm @sarahmaddox <body> <div id="map"></div> … </body> GoogleMaps JavaScript API
- 29. #APItechcomm @sarahmaddox <script asyncdefer src="https://maps.googleapis.com/maps/api/js ?key=YOUR-KEY-HERE &callback=initMap"> </script> Google Maps JavaScript API
- 30. #APItechcomm @sarahmaddox <script type="text/javascript"> varmap; function initMap() { map = new google.maps .Map(document.getElementById('map'), {center: {lat: -33.857, lng: 151.215}, zoom: 13 }); } </script> Google Maps JavaScript API
- 31.
- 32.
- 33. #APItechcomm @sarahmaddox Demo ofa REST API
- 34. #APItechcomm @sarahmaddox WWW URI orURL HTTP or HTTPS Web service APIs SOAP XML-RPC and JSON-RPC REST Web services REST APIs and more
- 35. #APItechcomm @sarahmaddox Calling theFlickr API <?xml version="1.0" encoding="utf-8" ?> <rsp stat="ok"> <photos page="1" pages="7" perpage="100" total="606"> <photo id=8554933095" owner="31065906@N08" secret="211xxxxxxx" server="8380" farm="9" title="IMG_4536" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8556044604" owner="31065906@N08" secret="b7bxxxxxxx" server="8368" farm="9" title="IMG_4533" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8556045230" owner="31065906@N08" secret="847xxxxxxx" server="8505" farm="9" title="IMG_4529" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8554934541" owner="31065906@N08" secret="9b38xxxxxx" server="8112" farm="9" title="IMG_4527" ispublic="1" isfriend="0" isfamily="0" /> Get a list: ● Request ● Response Get a photo: ● Request ● Response
- 36.
- 37.
- 38.
- 39.
- 40. #APItechcomm @sarahmaddox https://api.flickr.com/services/rest/? &method=flickr.people.getPublicPhotos &user_id=31065906@N08 &api_key=KEY-GOES-HERE Flickr APIrequest http://www.flickr.com/services/api/keys/apply/
- 41. #APItechcomm @sarahmaddox A Chromeadd-onAdvanced REST Client Testing web services and REST APIs
- 42. #APItechcomm @sarahmaddox <?xml version="1.0"encoding="utf-8" ?> <rsp stat="ok"> <photos page="1" pages="7" perpage="100" total="606"> <photo id="8554933095" owner="31065906@N08" secret="211xxxxxxx" server="8380" farm="9" title="IMG_4536" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8556044604" owner="31065906@N08" secret="b7bxxxxxxx" server="8368" farm="9" title="IMG_4533" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8556045230" owner="31065906@N08" secret="847xxxxxxx" server="8505" farm="9" title="IMG_4529" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8554934541" owner="31065906@N08" secret="9b38xxxxxx" server="8112" farm="9" title="IMG_4527" ispublic="1" isfriend="0" isfamily="0" /> Calling the Flickr API
- 43.
- 44. #APItechcomm @sarahmaddox HTTP protocol- what we’ve ignored <?xml version="1.0" encoding="utf-8" ?> <rsp stat="ok"> <photos page="1" pages="7" perpage="100" total="606"> <photo id=8554933095" owner="31065906@N08" secret="211xxxxxxx" server="8380" farm="9" title="IMG_4536" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8556044604" owner="31065906@N08" secret="b7bxxxxxxx" server="8368" farm="9" title="IMG_4533" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8556045230" owner="31065906@N08" secret="847xxxxxxx" server="8505" farm="9" title="IMG_4529" ispublic="1" isfriend="0" isfamily="0" /> <photo id="8554934541" owner="31065906@N08" secret="9b38xxxxxx" server="8112" farm="9" title="IMG_4527" ispublic="1" isfriend="0" isfamily="0" /> Types of requests: ● GET ● POST, PUT, DELETE, more Request/response: ● Header and body ● Status ● Data types
- 45. #APItechcomm @sarahmaddox Components ofAPI documentation
- 46. #APItechcomm @sarahmaddox What’s inAPI docs Conceptual Overviews Concepts Use cases Practical Quick start Tutorials Sample code Reference documentation Hand-written Auto-generated (Javadoc and others) Advantage of auto-generation Disadvantage of auto-generation
- 47. #APItechcomm @sarahmaddox /** * Shortdescription here. * More description. * Can contain links to other parts of the doc: {@link NAME}. * Can contain <strong>HTML tags</strong>. * Ends with special "block tags" denoting specific sections of the page. * * @param argument1 description of a parameter * @param argument2 description of a parameter * @return description of what the method returns */ Generated docs - Javadoc comments
- 48. #APItechcomm @sarahmaddox /** * Printsthe user’s favourite toy. * The printed string includes some predefined text and the * <strong>color</strong> and <strong>type</strong> of the toy. * * @param color A string containing the color of the toy. * @param toy A string containing the type of toy. */ private void printToy(String color, String toy) { String s = String.format("My favorite toys are %s %s.", color, toy); System.out.println(s); } Example of a Javadoc comment
- 49. #APItechcomm @sarahmaddox Examples ofAPI documentation
- 50. #APItechcomm @sarahmaddox Example documentationfor a JavaScript API Google Maps JavaScript API Getting started: http://goo.gl/uc8nL How-to guides for common use cases: http://goo.gl/IDmSPg Reference: http://goo.gl/W2yaZ
- 51. #APItechcomm @sarahmaddox Example documentationfor a REST API Twitter REST API Overview and getting started: http://goo.gl/QVRN8y How-to guides for common use cases: http://goo.gl/B46St5 Reference: http://goo.gl/ie0gpE
- 52. #APItechcomm @sarahmaddox Example documentationfor a Java-based API Google Maps Android API Overview: http://goo.gl/pPAMq Getting started: http://goo.gl/fgdUM How-to guides for common use cases: http://goo.gl/JlVOcQ Reference: http://goo.gl/ky1ijm
- 53. #APItechcomm @sarahmaddox Working withan engineering team
- 54. #APItechcomm @sarahmaddox Sit withthe team Grok teamwork Be the advocate for your audience - those “other” developers Get to know the tools Gather and share information A day in the life
- 55. #APItechcomm @sarahmaddox What aboutcode? Code http://goo.gl/JII3O0 http://ffeathers.wordpress.com/ 2013/12/21/how-to-write-sample-code
- 56.
- 57. #APItechcomm @sarahmaddox How toget started Get the tech Show the ‘tude Play with some APIs Do some docs Follow Hacker News Follow up on this presentation https://news.ycombinator.com MDN and WebPlatform.org
- 58. #APItechcomm @sarahmaddox What isan API? Our role and audience API types Demos of two APIs Components of API documentation Examples of API documentation Working with an engineering team How to get started
- 59. #APItechcomm @sarahmaddox Why anAPI tech writer? APIs are the communication channel of the connected world. API developers need help hooking their app up to someone else’s API. Tech writers who can give that help are in a very good position.
- 60. #APItechcomm @sarahmaddox “There isno line where you suddenly cross over from non-coder to coder, or from fake developer to real developer. There’s no high priesthood. You start learning, and then you just keep going.” Noah Veltman Code, the newsroom, and self-doubt
- 61. #APItechcomm @sarahmaddox Twitter @sarahmaddox Google++sarahmaddox Slideshare sarahmaddox Blog ffeathers.wordpress.com Contacting me