IT & Software
Other
Technical Writing
Learn API Technical Writing 2: REST for Writers
4.6 (1,384 ratings)
Course Ratings are calculated from individual students’ ratings and a variety of other signals, like age of rating and reliability, to ensure that they reflect course quality fairly and accurately.
6,115 students enrolled

Learn API Technical Writing 2: REST for Writers

API Documentation 2: Teaches technical writers how to document REST. No programming experience required.
4.6 (1,384 ratings)
Course Ratings are calculated from individual students’ ratings and a variety of other signals, like age of rating and reliability, to ensure that they reflect course quality fairly and accurately.
6,115 students enrolled
Created by Peter Gruenbaum
Last updated 7/2020
English
English
Preview this course
Learn API Technical Writing 2: REST for Writers
Current price: $27.99 Original price: $39.99 Discount: 30% off
5 hours left at this price!
Buy now
30-Day Money-Back Guarantee
This course includes
  • 1.5 hours on-demand video
  • 2 articles
  • 21 downloadable resources
  • Full lifetime access
  • Access on mobile and TV
  • Certificate of Completion
Training 5 or more people?

Get your team access to 4,000+ top Udemy courses anytime, anywhere.

Try Udemy for Business
What you'll learn
  • Understand the basics of how REST works.
  • Understand the basics of authentication and authorization.
  • Create reference documentation for REST requests.
Requirements
  • Students should have either taken the Udemy course "Learn API Technical Writing: JSON and XML for Writers" or else be very familiar with how to document JSON and XML.
  • You will need a Word Processor (such as MS Word, Apple Pages, or Google docs). The Chrome browser is recommended for some of the exercises.
Description

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:

  • 12 videos that:
    • Provide background information on REST APIs
    • Break down REST requests into their various pieces with examples
    • Show real-time, narrated writing of REST documentation
    • Provide overviews of authentication and authorization for REST
  • 7 hands-on exercises to lead you through making and documenting REST requests
  • 7 short quizzes to keep you on your toes
  • PowerPoint presentations as a resource for every video lecture
  • A Microsoft Word document you can use as a template for REST reference material

The course takes approximately 3 hours and 30 minutes to complete, depending on how fast you are with the exercises.

Who this course is for:
  • This course is designed for technical writers with experience writing end-user documentation and want to learn how to write API documentation. No prior programming or REST is required, but knowledge of JSON and XML is required.
  • This course is also helpful for technical writers with programming experience who want details on best practices for documenting REST.
Featured review
Steve Garriott
Steve Garriott ( 6 courses, 3 reviews )
a year ago
This course came along just in time as I was given the task of writing up API docs. I'm still figuring out the best way to document the current batch of requests, but this course has given me the background info I needed to at least look like I knew what I was doing while I was learning to do it :)
Course content
Expand all 21 lectures 01:44:25
+ – Introduction
2 lectures 12:41

This introduction explains:

  • What will be covered in the course
  • What APIs are
  • Why API documentation is important
Introduction
Preview 05:07

This lecture covers what REST is. At the end, students should know:

  • REST is a type of web API
  • The difference between design patterns and protocols
  • How RESTful APIs use HTTP, requests, responses, and resources
  • How REST compares to SOAP
REST
Preview 07:34

Answer the following questions about REST.

REST
3 questions
+ – REST
14 lectures 45:04

This lecture covers how REST requests work. At the end, students should understand:

  • What a request is
  • The different parts to a request:
    • Method
    • URL
    • Query parameters
    • Headers
    • Body
Requests
04:37

Identify part of a REST request

REST requests
4 questions

This lecture covers REST resources. At the end, students should understand:

  • What a resource is
  • How resources are represented in URLs
  • What endpoints are
  • How to specify either multiple or singular resources
  • How resources can contain other resources
Resources
03:16

Short note on resource names

Plural resource names
00:37

Choose the most likely resource for the given task.

Resources
3 questions

This lecture covers HTTP methods. At the end, students should understand:

  • What a method is
  • What are CRUD operations
  • When the methods GET, POST, PUT, and DELETE are used
Methods
04:33

Match up the actions with the most appropriate method.

Methods
5 questions

This exercise has you making REST calls to learn how to use the different HTTP methods.

Exercise 1 -- Making REST requests
5 pages

This exercise teaches you how to document the method and the URL for a resource.

Exercise 2 -- Document method and resource URL
1 page

This lecture covers query parameters. At the end, students should understand:

  • What query parameters are
  • How they are used in REST
  • How to document them
Query Parameters
08:47
Query Parameters
3 questions

IMPORTANT: NPR has recently stopped making the API available that's used in this exercise. I am in the process of replacing it with a new exercise.  Please skip this and check back later.

Exercise 3 -- Make API requests with query parameters
3 pages
Exercise 4 -- Document query parameters
2 pages

This lecture covers headers. At the end, students should understand:

  • What headers are
  • How to use headers to specify formats
  • How to use headers for authorization
  • How to document headers
Headers
04:28
Headers
3 questions
Exercise 5 -- Document headers
1 page

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:

  • The difference between authentication and authorization
  • What app keys are
  • What OAuth is and a bit about how it works
  • Generally, how to document authentication and authorization
Authentication and Authorization
12:46
Authentication and Authorization
4 questions

This lecture covers request bodies, response bodies, and errors. At the end, students should understand:

  • Where is structured data used in REST?
  • What URLs in response data means
  • Sample requests and responses
  • How to document HTTP status codes
Request Bodies and Responses
06:00
Exercise 6 -- Document status codes
1 page
+ – Putting It All Together
5 lectures 30:39

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.

Putting It All Together
18:08
Exercise 7 -- Creating full reference documentation
3 pages

This lecture covers tools for documenting and calling REST APIs. At the end, students should understand:

  • How tools can help
  • The differences between single source tools, content management systems, and autogenerated documentation tools
  • What Markdown is
  • How to use a REST client to make REST API calls
Tools for REST Documentation
07:04

This lecture is a review of the course, and includes:

  • A summary of each lecture
  • A description of next steps to writing complete REST API documentation
Review and Next Steps
04:56
Bonus Lecture: Offer for Next Course in the Series
00:31