Moving into API documentation writing Ellis Pratt @ellispratt
About me Director at Cherryleaf, a technical writing services and training company in the UK (with an API training course)
About you Who creates API documentation today?
Overview 1. What is an API? 2. APIs and the role of documentation 3. The role of an API documentation writer 4. The skills you need 5. The tools 6. Becoming an API documentation writer Image: Tim Peake
1.What is an API?
A way for applications to exchange information
Lots of websites use information from APIs Find a GP near to your postcode Information is requested from the NHS Choices API and displayed on the web page www.whereilive.norfolk.gov.uk
Behind the scenes Request App API Developer API Team
What developers do with APIs Developers write code to take the data provided in the response and use it in their applications (“parsing”) App API NHS application containing list of GP practices in a database Developer There is code in the Web page to request data and then display the data on a map
http protocols Users make requests for the http request -> resources on a Web server. API <- http response The server returns responses containing the information.
Components of a REST API
A hospital API An API will consist of a set of rules describing how an application can interact with it API and the mechanisms that allow such interaction to happen.
Example - Your NHS number The API might state it wants the NHS number in: numerical (9434765919) or alphanumerical string (“943-476-5919”) format.
Resources These are the “information objects” the API can exchange Resources have data associated with them (e.g. the patients’ names) Request App API
Endpoints Request App API http://ABC-hospital.nhs/patients/ A http address where you can find a resource
API Rules A hospital API will consist of a set of rules describing how an application can interact with it (specifically, a resource): Create/Add information (Post) Request information (Get) Update information (Put/Patch) Delete information (Delete) (and run an application)
Requests to an API Get me Jane Brown’s records GET http://ABC-hospital.nhs/patient/ JaneBrown Get me a list of all the patients curl --get -k --include "http://ABC- leaving hospital today hospital.nhs/patient/?name=jane brown&NHS=9434765900" -H "X-Key: ABC12345" -H "Accept: text/plain Get me the Consultant’s name who is attached to Mrs Brown curl -X GET -H "Cache-Control: no- cache" -H "Postman-Token: 97bb9ba5- f763-208e-b9e4-5d7bd3861835" "https:// fhir-open-api-dstu2.smarthealthit.org/ etc Patient/1551992"
How do the API team create APIs? They may use an API Specification API They may make REST calls in the programming language they are using API Team
They may use a type of API Specification API Specification tools can generate the code for REST calls in a programming language. Programmers can then add this code to their application.
2.APIs and the role of documentation
What content goes into an API document? Content Buzzword A clear definition of what Resource description resource it represents Parameters, Request The accepted input submission example The produced output Request response example Links (where can you go to find Endpoints what exactly)
Automatically generated content When you describe your API using the Swagger or RAML specification, some tools can read those specifications will generate an interactive documentation output.
Explain what it does What it does The overall process Any underlying concepts
Signing up for an account Signing up for an account Getting API authorisation keys
The 3-30-3 goal The 3-30-3 goal 3 seconds - what it does 30 seconds - why you should use it 3 minutes - to do something
TTFHW - Time to first "Hello World" A simple exercise How quickly you can get an application to output “Hello World”? For APIs it might be how to construct a request and receive a valid response.
Tutorials For different programming languages To get to “Hello World”
Why do we need code samples? REST APIs aren’t tied to a specific programming language So developers may need advice on how to submit HTTP requests in their particular programming language
Creating code samples Some API providers decide to provide one code sample curl --get -k --include "http://ABC-hospital.nhs/ (usually in cURL) and let the patient/?name=jane developer extrapolate the brown&NHS=9434765900" -H "X- Key: ABC12345" -H "Accept: format in his or her own text/plain programming language.
Creating code samples Others want to encourage developers to use their API, and want to make it as easy as possible by providing code samples.
Creating code samples - Don’t panic! In some cases, developers supply the code samples You briefly add comments to the code samples. The patterns for making REST requests in different programming languages follow a common template.
3.The role of an API documentation writer
What Technical Authors do Technical Author Task-based content To a less technical audience
What Technical Authors do Technical Author Filter content for different audiences Publish to different media Re-use content Localise
What API doc writers do API Writer Reference-based content* To a technical audience Single use document English only * Mostly
There are some differences Technical Author API Writer Task-based content Reference-based content To a non-technical audience To a technical audience Re-use content Single use Localise English only
Developers may be writing Comments in code The documentation Using their own tools
API doc writers’ tools Less sophisticated Built to suit the developers’ workflow Low cost, open source Simple markup
Improving the tools It’s getting there Lightweight DITA may help
5.Becoming an API documentation writer
The grass is greener? Lots of software developer are currently working on APIs
Let’s look at some vacancies On reed.co.uk from mid- February 2016……
Of the 5,000 UK Technical Authors on LinkedIn 173 included “API” in their profile Search carried out on 15/2/2016
Finding a unicorn “Finding a technical writer who commands a high degree of English language fluency in addition to possessing a deep technical knowledge of Java, Python, C++, .NET, Ruby, and more is like finding a unicorn.” Tom Johnson Flickr image: Owlana
A lot of recruitment is by word of mouth Following entrepreneurs as they more from business to business
Improve skills You can get by with a wide and shallow understanding of programming
Improve skills Learn Python basics Understand what the tools can do Assist on open source projects More training courses are emerging
What are the takeaways? It’s a growing area It’s changing rapidly It requires more technical skills It’s well paid
For more information firstname.lastname@example.org @ellispratt