Building Lob’s API: Dos, Don'ts, and Everything Else We've Learned
When we first started at Lob, we took a look at industry leaders in REST API design and also at other companies with APIs to evaluate key elements we wanted in our API. There’s no widely adopted standard that works for all cases, but our API is the lifeblood of our company. That's why we set out to create the simplest one. We wanted to share some of the best practices we picked up along the way, even at the risk of telling you what you already know.
The best REST API designs all have some key requirements in place that we whittled down:
Clearly follow HTTP specifications
Put the developer first, strive for ease of use to spur adoption
Given these requirements, here are some of the top of mind items that we kept revisiting while creating our REST API. Roy Felding first introduced REST and you can read his dissertation for even more info. RESTful principles enjoy wide adoption and we did our best to follow standards as closely as possible.
1. Documentation, Documentation, Documentation.
I’d argue that documentation is one of the most important parts of your API. It should be easy to read and find. It will be the #1 destination any developer checks before attempting an integration method. Provide examples of complete request and responses and even better use examples that can be copy-pasted directly into terminal. We probably went through about 10 revisions on our documentation and it's still constantly being updated.
2. API paths should clearly show a hierarchical relationship between resources and objects
Separate your API into logical resources (they should be nouns!) where the different HTTP request methods (GET, POST, PUT, DELETE) have specific meanings
Make your IDs easily understood and descriptive. Since there was so many different IDs for our different endpoints, we wanted to make sure a user could take a cursory glance and immediately know what the ID represented.
Do not return total counts or loop through entire databases to get the large count
We’re always looking for ways to improve our API so please get in touch with any comments you might have. Hopefully this will be a great start and good guidance for any of you out there looking to build your own API.
This blog provides general information and discussion about direct mail marketing and related subjects. The content provided in this blog ("Content”), should not be construed as and is not intended to constitute financial, legal or tax advice. You should seek the advice of professionals prior to acting upon any information contained in the Content. All Content is provided strictly “as is” and we make no warranty or representation of any kind regarding the Content.
Stay up-to-date with Lob’s latest
We have a lot cooking in the Lobster tank! Sign up for our newsletter to never miss a beat.