Publishing REST APIs Workshop
In the Documenting REST APIs workshop, we used a simple Weather API from Mashape to demonstrate how to use and create a REST API. In this course, we’ll explore various tools to publish information from the Mashape Weather API that we covered in the previous course. Some of the publishing approaches we’ll explore are the following:
- Github wikis and Markdown
- API Blueprint
- Jekyll and static site generators
- Help authoring tools such as Flare
With almost every one of these tools, you’ll deploy a sample file to publish content.
Regardless of the tool you choose, there are some common design patterns with API doc, such as the following:
- Structure and templates
- Website platforms
- Abundant code examples
- Single-click navigation
- Interactive API explorers
The tools you choose depend partly on your requirements. If you have to account for translation, content re-use, versioning, authentication, or PDF output, these requirements impact your tool decisions.
The first course, Documenting REST APIs workshop, is the recommended (but not required) prerequisite.
- Text editor. (Sublime Text is a good option (both Mac and PC). On Windows, Notepad++ and Komodo Edit are also good. )
- Git. See Set Up Git for more details.
- Filezilla. This is an FTP client for transferring files to a web host.
Note that your computer needs to be able to connect to a wifi network.
The workshop lasts 3 hours.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.