Search results

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.

Prerequisites

The first course, Documenting REST APIs workshop, is the recommended (but not required) prerequisite.

Required software

Note that your computer needs to be able to connect to a wifi network.

Duration

The workshop lasts 3 hours.

About Tom Johnson

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.