Hilary Weaver-Robb
Senior Software Engineer | Quicken Loans
API documentation is important, especially when consumers outside of your team or company are using your APIs.
Consumers should understand how to use your API in various scenarios, and sometimes documentation isn’t enough. Including real code examples (not just snippets) of how your API works will help your consumers fully understand how to use it and get it up and running much quicker. Implementing your API from a consumer-focused perspective can help improve how it functions and the overall experience for consumers.
Every quarter, our Technology team members participate in Hack Week, a week dedicated to innovation, improvement and hacking away at projects we aren’t normally able to tackle during development time.
Recently, Hack Week came around, and I had a problem. I was in need of a project. I knew there was room to improve our API documentation, but I wasn’t sure how to go about it. I decided to spend Hack Week exploring and improving our API documentation from our consumer’s perspective and applying some AWS training in the meantime.
As a Senior Software Engineer with a focus in testing, I actually enjoy updating our team’s documentation for our API consumers. I’m always happy to help our clients get up and running with our APIs or help them understand how they work. In our documentation, we laid out the steps to authenticate against our API and get a token. Then, we outlined how to use that token in subsequent API requests. I knew the documentation could be improved by making it more demonstrative of what needs to happen in practice, but I didn’t want to just document a bunch of code. I decided to write an example application, which any of our clients could use as a guide, and link to it in our documentation.
Deciding On AWS Lambda
At the time, I was learning about AWS by taking some trainings for software engineers. I realized that implementing an AWS Lambda function would be a great way to both cement my AWS knowledge and build a simple but effective functioning example of our APIs. This would be accessible to our internal consumers, and they could actually execute the code and see the results in CloudWatch logs (not just in GitHub).
As a serverless service, AWS Lambda lets you run code without having to set up supporting infrastructure. Simple API calls, like I was planning, are perfect for Lambda, and to make it even better, I wouldn’t have to worry about provisioning servers or making sure they are running when people want to test the example code.
AWS Lambda supports a number of different programming languages, but I determined that using Node.js would make it as quick and simple as possible. I wanted to keep the deployment simple (just copying and pasting my code in the AWS Console), so that seemed like the best option. I’ve written a number of API tests using Node.js, so that, at least, wouldn’t be new territory.
