This is the second in a series of courses for technical writers who want to learn how to write API documentation. The first course is called "Learn API Technical Writing: JSON and XML for Writers", and it is recommended that you first take that course, unless you are very familiar with JSON and XML, and how to document them.
This course teaches how to document REST APIs. No programming experience is required, but technical writers with programming experience who want to know more about REST APIs will still find it useful.
What are APIs?
APIs (Application Program Interfaces) define how software systems talk to each other, and API documentation is a rapidly growing field. There is a strong need for writers who can understand APIs and explain them so that software developers can understand how to use them. API writers get to be in on the cutting edge of technology in high-paying positions.
What is REST?
REST (Representational State Transfer) is a popular style of web API, and it's used to communicate data between devices and servers. Different data is contained in different parts of the API requests and responses, and this course explains what those different parts are and how to document them.
What is in This Course?
By the end of the course, you will understand what REST is and how to read and document REST requests and responses. In this course you'll find:
The course takes approximately 3 hours and 30 minutes to complete, depending on how fast you are with the exercises.
This introduction explains:
This lecture covers what REST is. At the end, students should know:
Answer the following questions about REST.
This lecture covers how REST requests work. At the end, students should understand:
Identify part of a REST request
This lecture covers REST resources. At the end, students should understand:
Short note on resource names
Choose the most likely resource for the given task.
This lecture covers HTTP methods. At the end, students should understand:
Match up the actions with the most appropriate method.
This exercise has you making REST calls to learn how to use the different HTTP methods.
This exercise teaches you how to document the method and the URL for a resource.
This lecture covers query parameters. At the end, students should understand:
This lecture covers headers. At the end, students should understand:
Note: This lecture is technically the most difficult. If you are finding it hard to understand, don't get discouraged. Just skip it and come back to it at the end.
This lecture covers authentication and authorization. At the end, students should understand:
This lecture covers request bodies, response bodies, and errors. At the end, students should understand:
This lecture covers how to put all of the information from the course together to write reference API documentation. Two examples are documented in real time.
This lecture covers tools for documenting and calling REST APIs. At the end, students should understand:
This lecture is a review of the course, and includes:
Peter founded SDK Bridge to bring together his love of technology and writing. After 10 years as a software developer, he learned the skill of API writing at Microsoft. Since then, he has worked as an API writer to describe APIs for eCommerce, automobile traffic prediction, electric utilities, mobile phones, and tractors, just to name a few. In addition to API and SDK documentation, he creates video tutorials for software developer audiences. Peter received his BA in Physics from the University of Chicago and his PhD in Applied Physics from Stanford University.