Nurturing References of REST APIs (Course)
This course retells some Internet history to explain the rationale for REST APIs, before delving into the craft of writing useful API references.
References are a vital part of the developer documentation of large and complex systems because they support effective collaboration between experts to capture detail.
Instructor-led, live online course, 16 hours in class, offered at Polytechnic University of Porto since 2024.
Learning objectives
At the end of the module, students will be able to:
- Identify reasons and decisions that led to the widespread usage of REST APIs.
- Identify details of commands and responses of REST APIs, and how developers specify them.
- Walk in the shoes of client developers to answer their questions in references.
- Visualize large APIs using UMLish diagrams.
- Improve incomplete and ambiguous API specifications.
Why am I teaching this?
The demand for technical writers that can document APIs keeps rising, as companies adopt APIs to integrate their business with partners or, using micro-services, to coordinate the work of multiple teams. REST APIs are a style of communication among systems and their developers that has grown in popularity because of their simplicity, scalability, speed, and ability to handle structured data.
Traditionally, API documentation requires a rare breed of person with the dual capacity of writing and programming. However, the adoption of Internet technologies made the APIs more approachable, both for developers and for technical writers.
What happens in class?
The class is organized in lessons as follows.
- We learn Internet history to understand the rationale behind historic decisions that are still visible in REST APIs and that impact our daily work.
- We learn the OpenAPI specification, a standard textual format that is the basis to collaborate with developers, and the ecosystem of tools and functionality enabled by the standard.
- We learn to write good descriptions for parts of REST APIs, and to group APIs into understandable chunks.
- Finally, we briefly consider other kinds of API documentation beyond references.
The course only works if students engage in class. In the University course, students that engage in class get a passing grade. A final exam tests the knowledge of students and may result in a higher grade.
Course history
The workshop was developed in 2022 for the Advanced Autumn School in Porto, and was then included as a module in the 2023/2024 restructuring of the Postgraduate Diploma on Technical Communication.
| Date | Place | Class | Place |
|---|---|---|---|
| 2024-05 | Virtual | 12 students | “Documentation of REST APIs” at Polytechnic University of Porto. |
| 2022-11-26 | Porto | 10 students | “Nurturing References of REST APIs” at Advanced Autumn School. |
| 2018-06-26 | Lisbon | 8 persons | “Writing API References” presented at Technical Writers @ Lisbon. |
Available yearly or on demand
This training is an instructor-led module available live online or on premises. The training room requires a projector and students must be able to read and write in class, possibly in laptops.
In 2023/2024, this training is offered between 31-May and 26-Jun (4x3h+4h) for €167 as an instructor-led, live online course, integrated in the Postgraduate Diploma on Technical Communication. A similar offer is expected for 2024/2025.
Contact me for details: px@acm.org — LinkedIn — +351 91 784 2996