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:

1. Clearly follow HTTP specifications
2. 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

/v1/jobs
/v1/jobs/{JOB_ID}
/v1/objects
/v1/objects/{OBJECT_ID}/
/v1/addresses
/v1/addresses/{ADDRESS_ID}
...

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.

job_d1a62016cba4ee83  
obj_2d9b85fad42f64f8  
adr_575a1b720bcdd6dc  

3. CRUD operations should always be handled with HTTP protocol behaviors

4. Always version your API to make it easier to iterate and prevent invalid request from hitting new or old endpoints

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.

5. JSON responses and prettyprint by default. As you can see below JSON is quickly becoming the standard output for APIs.

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.

6. When you have Pagination always return links for the so the user doesn’t need to generate the links on their own

• "next_url": "https://api.lob.com/v1/jobs?count=2&offset=5"
• "previous_url": "https://api.lob.com/v1/jobs?count=2&offset=3"
• 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.

*Other great resources for further reading: Vinay Sahni's Pragmatic RESTful API, Matt Gemmell's API Design Post, API Design is UI for Developers, Apigee's API Best Practices

‍