Publishing REST APIs Workshop
Workshop description
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
- Swagger
- API Blueprint
- RAML
- Jekyll and static site generators
- Miredot
- Readme.com
- 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.
Sponsored
Prerequisites
The first course, Documenting REST APIs workshop, is the recommended (but not required) prerequisite.
Required software
- 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.
Duration
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, agent skills, tech comm careers, and more. Check out my AI courses for more on the latest in AI and tech comm. If you're looking for info about documenting APIs, see my API documentation course.
If you're a technical writer and want to keep on top of the latest trends in tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me.
Finally, I want to note a couple of things. I usually write the first drafts of my posts myself and then use AI to improve accuracy, clarity, and detail in places, so my writing is a mix of human and AI. (Hopefully that's not too off-putting.) Also, the opinions I express on my blog are my own perspectives, not those of my employer.