Building a RESTful API
•
2 likes•822 views
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.
Recommended
More Related Content
Viewers also liked
Viewers also liked (18)
Recently uploaded
Recently uploaded (20)
Building a RESTful API
- 1. Building a RESTful API Best Practices The Lob Team www.Lob.com @Lob
- 2. 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
- 3. 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
- 4. 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
- 6. 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. www.Lob.com
- 8. API paths should clearly show a hierarchical relationship between resources and objects. /v1/jobs /v1/jobs/{JOB_ID} /v1/objects /v1/objects/{OBJECT_ID}/ /v1/addresses /v1/addresses/{ADDRESS_ID} ... Separate your API into logical resources (they should be nouns!) where the different HTTP request methods (GET, POST, PUT, DELETE) have specific meanings. www.Lob.com
- 9. 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 www.Lob.com
- 11. CRUD operations should always be handled with HTTP protocol behaviors. www.Lob.com
- 13. 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. www.Lob.com
- 15. JSON responses by default. JSON is quickly becoming the standard output for APIs. www.Lob.com
- 17. 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. www.Lob.com
- 19. 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
- 20. Other great resources for further reading: Vinay Sahni's Pragmatic RESTful API http://www.vinaysahni.com/best-practices-for-a-pragmaticrestful-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-fordevelopers/ Apigee's API Best Practices http://apigee.com/about/api-best-practices www.Lob.com
- 21. Questions or Thoughts? Tweet @Lob support@Lob.com www.lob.com/blog www.Lob.com