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.