Product
Mailgun Hack Day: Making our API documentation smarter
Each month our team has the opportunity to hack on whatever it is we want to hack on. A fun way to learn something new, collaborate with different team members or just tidy up something that has been bugging us.
PUBLISHED ON
Each month our team has the opportunity to hack on whatever it is we want to hack on. A fun way to learn something new, collaborate with different team members or just tidy up something that has been bugging us.
For January’s hack day, a few of us (Anton, Jesse and myself) set out to make some improvements to our API Docs.
Table of contents
Part 1: Your Mailgun settings injected into code samples
Part 2: Code samples are editable in the browser
The problem
Our API is well documented and has a good range of code samples for all the major programming languages. However, there are a couple of things we noticed about the workflow.
To try an API request, a developer would typically:
Copy a code sample to a text editor
Edit some parameters (e.g. sender, recipient, body text)
Go to their Mailgun Control Panel to copy their API key
Go back to the code editor and paste the key
Copy that sample to their command line and execute
For quickly exploring a new service or testing out a new endpoint, this seems like a couple of steps too many.
The solution
Part 1: Your Mailgun settings injected into code samples
Now the code samples we show you are a bit smarter. If you’re logged in to Mailgun, we will inject your API key and some smart defaults for you.
Therefore it’s just a matter of copy/pasting the code samples into your command line, executing, and they should work off the bat.
Part 2: Code samples are editable in the browser
We’ve also made the code samples editable. Using Ace editor, clicking on any code sample will turn it into a small in-browser text editor that you can make changes to.
Conclusion
API docs are instrumental to the user experience of a developer service. With the above changes shipped to production, we hope that trying out our API should be a lot easier for new developers exploring our service and existing developers that want to test or troubleshoot different API endpoints.
