Embed Size (px)
DESCRIPTION
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 we knew that our API would be the lifeblood of our company and set out to create the simplest one. Some of this may be obvious but we wanted to share some of the best practices we picked up along the way.
Citation preview
Building a RESTful API
Best Practices
The Lob Team www.Lob.com
@Lob
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. Here we will share some of the best practices we picked up along the way.
www.Lob.com
The best REST API designs all have some key requirements in place that we whittled down: 1. Clearly follow HTTP specifications http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
2. Put the developer first, strive for ease of use to spur adoption
www.Lob.com
REST was first introduced by Roy Felding and you can read his dissertation for even more info. http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
RESTful principles are widely adopted, here are some of the top of mind items that we kept revisiting while creating our REST API…
www.Lob.com
Documentation
www.Lob.com
www.Lob.com
Documentation is one of the most important parts of your API. 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.
API Paths
www.Lob.com
www.Lob.com
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}
...
www.Lob.com
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
Create Read Update Delete
www.Lob.com
www.Lob.com
CRUD operations should always be handled with HTTP protocol behaviors.
API Versioning
www.Lob.com
www.Lob.com
Always version your API to make it easier to iterate and prevent invalid request from hitting new or old endpoints. Over-communicate to your customers. Make sure they are notified in advance of any changes that may affect them so they have appropriate time to update applications accordingly.
JSON as Output
www.Lob.com
www.Lob.com
JSON responses by default.
JSON is quickly becoming the standard output for APIs.
Prettyprint
www.Lob.com
www.Lob.com
Prettyprint 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 it is pleasant to use.
Pagination
www.Lob.com
www.Lob.com
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.
www.Lob.com
Other great resources for further reading:
Vinay Sahni's Pragmatic RESTful API http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api Matt Gemmell's API Design Post http://mattgemmell.com/2012/05/24/api-design/ API Design is UI for Developers http://shkspr.mobi/blog/2012/03/api-design-is-ui-for-developers/ Apigee's API Best Practices http://apigee.com/about/api-best-practices
