Last Updated: 27 Jun 2023
|
Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
backend-tech:building-an-api-best-practices [Sep 25, 2018 06:19 PM] dordal [Building an API: Best Practices] |
backend-tech:building-an-api-best-practices [Jun 24, 2023 02:12 PM] 111.225.148.107 removed |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | = Building an API: Best Practices = | ||
+ | //**Update 25 Sept 2018: As a commenter points out, this 2012 article 'has not aged well'. I agree, and while I hope to update it at some point in the future, please see the comments ( and add comments!) for more modern best practices.**// | ||
+ | |||
+ | This doc outlines a few thoughts and best practices for building an API. This is based on my own experience building APIs, as well as examining popular APIs such as [[http:// | ||
+ | |||
+ | Be sure to check out these resources for more on API development: | ||
+ | * [[http:// | ||
+ | * The [[http:// | ||
+ | |||
+ | |||
+ | === REST vs. SOAP === | ||
+ | |||
+ | One of the early decisions you'll need to make is whether your API will be ' | ||
+ | |||
+ | //Note: To be fully RESTful, an API has to do a lot more than be accessible via a URL; APIGee has [[http:// | ||
+ | |||
+ | === JSON vs. XML === | ||
+ | |||
+ | Now that you've decided on your API will be RESTful, you should decide how you're planning to return data. There are two common choices: [[http:// | ||
+ | |||
+ | Many APIs today offer a ' | ||
+ | |||
+ | === GET & POST (and PUT, DELETE, etc.) === | ||
+ | |||
+ | Another decision if you're using a RESTful model: do you use GET or POST for calls? I'd strongly recommend you follow the HTTP & REST standards; e.g. use GET for all calls for retrieving data (getUser, getObject, etc.) and POST (or PUT) for all calls where you send data (addUser, updateUser, etc.). You can also use other less common methods such as DELETE if you need to do an operation like removing a resource. | ||
+ | |||
+ | === Use an Envelope === | ||
+ | |||
+ | You'll generally want to wrap all your API responses in an ' | ||
+ | <code language=' | ||
+ | // sample JSON envelope | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | Doing this allows for client handler code to behave the same way for all API calls, since it gets a responses back in a universal format. | ||
+ | |||
+ | === Handling Authentication === | ||
+ | |||
+ | Most APIs you build will require some sort of authentication. Generally you want to implement one of the following: | ||
+ | |||
+ | - Use an established authentication standard, like [[http:// | ||
+ | - Roll your own token based authentication; | ||
+ | - Roll your own [[http:// | ||
+ | |||
+ | I don't have a strong preference. Foursquare, Facebook and Twitter all went the oAuth route, and it's clearly an emerging standard, but it seems particularly useful for social applications & API designed for application-to-application communication. Many other APIs use their own authentication scheme, and a few use standard HTTP authentication. | ||
+ | |||
+ | === Handling Errors === | ||
+ | |||
+ | Errors in APIs are an interesting beast. There are generally two ways to handle them, and they' | ||
+ | |||
+ | There are also a number of cases where both are done; for example the foursquare API [[https:// | ||
+ | |||
+ | === Versioning === | ||
+ | |||
+ | You'll almost certainly want to version your API so you can make changes in the future without breaking your existing clients. I recommend a version string at the root, e.g. | ||
+ | < | ||
+ | http:// | ||
+ | http:// | ||
+ | </ | ||
+ | |||
+ | === Developer Key === | ||
+ | |||
+ | You might consider making your clients register for a ' | ||
+ | |||
+ | One interesting strategy here is BART' | ||
+ | |||
+ | === Usage Limits === | ||
+ | |||
+ | You may want to put some usage limits on your API, depending on its purpose and intended audience. Nearly every public API has rate limits, from Facebook to foursquare to bit.ly to Twitter. | ||
+ | |||
+ | === SSL vs. Not === | ||
+ | |||
+ | There' | ||
+ | |||
+ | SSL generally adds a 10%-15% overhead to a web transaction, |