Introducing the Postmark API Explorer
We believe strongly in providing a great “out of the box” experience with Postmark. Over the last year, we’ve invested in improving our official clients for .net, node.js, PHP, and Ruby. In addition, we’ve written about the importance of great documentation, and we know that customers agree.
Today, we’re excited to introduce another tool to help you get the most of all the features that Postmark provides:
Now Open: Postmark API Explorer #
The Postmark API Explorer is a new UI where you can try every endpoint in the Postmark API right from your browser. There’s no longer a need to run cURL commands in terminal to test things out (Though it’s totally fine if that’s your preference). You can try this UI right now, but come back, because we have more to share.
Are you curious about how this all works? Would you like to set this up for your own API? Read on!
We’ve got Swagger #
The Postmark team has been following an Open Source project called “Swagger” for a couple of years now. With Swagger, it is possible to describe REST APIs in a standard way using a simple YAML file. The benefit of doing so is that you’ve now got something that is both descriptive enough for humans to read and understand, and can be consumed by other tools. While Postmark is only using Swagger UI for now, the Swagger project offers a few tools to make API management easier with Swagger Codegen, the Swagger Editor, and more.
The Postmark API Explorer uses the Swagger UI tool to produce a dynamic API client and render each endpoint in the browser. One of our designers, Derek Rushforth, made some awesome style modifications to match our branding, but the core technology is Open Source and available for you to use with your API, today. It’s worth noting that if you’ll be serving Swagger UI from a different domain than your API, you will need to include proper CORS headers for your API’s endpoints.
Another benefit of using using the Swagger spec is that it’s is possible to generate API clients for many common languages. We’re not doing this for the Postmark clients yet, but we’re looking into generating them in the future.
- Python
- Java
- Objective-C
- Perl
- Scala
- Qt 5 C++
- Flash
- Javascript
- C#
- Ruby
- PHP
- And more...
Our plan is to use Swagger to provide even more clients for you. These clients may not be hand-coded, but keeping them in sync with an evolving API spec will be very easy. Additionally, the process of creating the clients is also far less error-prone than authoring API clients manually.
The actual Swagger spec is simply a document standard, this makes it easy to write your own tooling to consume Swagger API specs, so the possibilities here are endless.
Frequently, API designs start by describing REST endpoints, we think it’s a worthwhile investment to use a standard like Swagger. The resulting document can become a living document — one that has many downstream benefits to your team, and consumers of your API.
Check out the Postmark API Explorer, and let us know what you think!
