How We’re Demoing Developer Tools Using Hoot, Hosted On Glitch! 🎏

If you’ve ever had to learn how to use a new developer tool (like a JavaScript library or a CI tool), chances are you’ve gone through a workflow like this:

1. Grabbed a code sample from the docs.
2. Set up a local test environment and test app to tinker around with the code sample.
3. Adjusted the code until you find a workflow that works for you.

At ReadMe, we sympathize with the fact that this process is no small undertaking for anyone. Which is why we’re constantly exploring ways to democratize this process and why we’re really excited about Glitch!

Glitch is a web hosting platform with tools that make it easy for anyone to view and build off of your source code. The best (and perhaps most iconic) part of Glitch is the “Remix” button that’s on every Glitch app—just click the button and within seconds, you have your own fully editable copy of the application running in the cloud.

Many leaders in the developer tooling space (such as Slack and Twilio) use Glitch to show live, “remix”-able demos of their tools in action. And it completely makes sense—imagine clicking a “Remix” button and being able to skip the first two steps of the above process! We’ve been working on some really exciting developer tools ourselves, so it was fitting that we join the fun. 💃

Meet Hoot, our freshly open-sourced and first official Glitch app! 🎉 Hoot is a simple social media website where you can:

• View other users’ “hoots.” (Which are status messages that are 280 characters or less… sound familiar?)
• Create your account on Hoot. (Complete with your own custom Owl-vatar!)
• Like and respond to other users’ hoots, and post your own hoots.
• And best of all, interact with Hoot via a REST API and view the docs (hosted on ReadMe, of course)!

Why Hoot?

When explaining APIs to my non-technical friends, I like using Twitter as an example because it’s easy to explain the idea of third-party Twitter clients through the idea of viewing and sending tweets as a series of HTTP requests. For our first project on Glitch, we wanted to demonstrate several of our tools at once, through an API use case that people are familiar with. Well what better way is there to demo ReadMe’s developer tools than through a basic little Twitter clone?

We actually built Hoot several years ago as an internal demo site at ReadMe to do just that! But since the application and the source code have been internal for so long, we had to make some serious updates to make sure that Hoot would be Glitch-ready. Here are some of the considerations we made when rebuilding Hoot from the ground up:

• Simplicity: The code should be something people can easily edit and integrate into their own applications, so we want the code to be easy to follow and easy to replicate (especially for the files that are showcasing ReadMe tools!).
• Organization: We want to make sure each tool demonstrated in Hoot is separated into its own file, while maintaining a simple folder hierarchy with clear file naming conventions.
• Context: We want to let the code tell as much of the story as possible, but we included lots of inline comments to provide explanations for some of the important and complex sections, such as authorization, JWT, and API Metrics.
• Glitch-friendliness: This is a Glitch app, after all! We designed a few ReadMe-powered workflows with Glitch in mind to minimize friction between clicking the “Remix” button and getting Hoot connected to your ReadMe documentation. We even built a GitHub CI tool!

As mentioned above, Hoot contains a lot of exciting ReadMe tools behind the scenes—I’ll go over the highlights (and provide links to the corresponding links to the code in the Glitch app itself) below.

Swagger Inline

Swagger Inline is a JavaScript library that allows you to document your API using inline comments. (Think JSDoc, but for your OpenAPI document.) We recommend writing the comments directly above each of your endpoints—this makes it easy to ensure that your API endpoints and the corresponding documentation are updated together. Swagger Inline will take these comments and generate an OpenAPI file, which you can then upload to ReadMe.

To see this working in Hoot, check out:

• bin/openapi/generate.sh for the usage of Swagger Inline.
• The files in the api/ directory for the annotated API endpoints.

rdme

rdme is the command-line interface (CLI) for ReadMe's HTTP API. You can use it to upload a whole folder of Markdown files or an OpenAPI document to ReadMe all with a simple terminal command! The CLI has simple prompts for first-time users to make it easy to handle versioning (i.e. uploading new vs. existing files).

To see this working in Hoot, check out:

• bin/openapi/upload.sh for a full OpenAPI generation (see Swagger Inline above) and upload workflow that uses rdme.
• You can test out this entire workflow by running npm run upload in your console. (See below for the workflow in action!)

ReadMe JWT Login

JSON Web Token (JWT) is an open standard for securely sending data between two parties. To put it another way—once your users authenticate into your system, you can easily generate a secure URL that automatically logs them into their ReadMe documentation! When your users are logged in, they’ll be able to:

• View their own API keys and other custom variables pre-filled in the documentation.
• Send authenticated requests to your API using the API Explorer.
• View their API logs directly within the reference documentation. (See API Metrics below!)

To see this working in Hoot, check out:

• middleware/jwt.js for the full construction of the JWT.

Last but not least… API Metrics!

API Metrics are a part of ReadMe’s newest product: Developer Metrics! Once you’ve set up one of our integrations, API Metrics will be able to provide you with comprehensive data on how your API is being used. Plus, your users will be able to view their API usage logs directly within the documentation itself, making onboarding and debugging issues a breeze!

To see this working in Hoot, check out:

• middleware/metrics.js for a working example of the Node.js/Express middleware.
• The last few lines of middleware/jwt.js for how to set the response headers for the Cloudflare worker.

Tying It All Together

Now that we’ve gone over all of the ReadMe tooling featured in Hoot, what does this mean for you and your users? Well, dear reader, users of Hoot will not only be able to log in to Hoot and send “hoots” (like on Twitter), but also…

• Automatically log into the API documentation via ReadMe JWT Login using their Hoot credentials and send authenticated API requests from the API explorer.
• View their entire Hoot usage directly within the API reference documentation thanks to API Metrics.

And since this is a Glitch app that is fully "remix"-able, you can instantly create your own copy of Hoot with a simple click, connect it to your own ReadMe project, and edit it as you please! As the newest member of the Hoot developer team, you’ll be able to:

• Maintain your OpenAPI file for the Hoot API directly within your code comments, thanks to Swagger Inline.
• Upload (and subsequently sync) your OpenAPI file to ReadMe using the rdme CLI tool.
• Analyze comprehensive usage statistics about the Hoot API in the ReadMe API Metrics dashboard.

Coming Soon... More Glitch Apps!

While Hoot is a fantastic way to demo several of our different tools at once, we're also thinking about smaller Glitch apps that we can build in the future to showcase individual aspects of the ReadMe platform. If you’re curious about how JWT works, stay tuned for a simple Glitch tutorial that you’ll be able to remix directly from the ReadMe dashboard! 👀

Have any feedback for how we can make Hoot even better? Feel free to open up an issue or pull request on our GitHub repository! And, be sure to tweet at us with any other ideas for Glitch apps you'd like to see. 🎏