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:
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.
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.
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.
Overcommunicate to your customers. Make sure that any changes that may affect them they know about it in advance and have appropriate time to update applications to fit.
Pretty print by default is one of those small things but makes your API that much easier to use. It makes it easy for customers who are debugging to easily read data and pleasant to use.
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.