Morning all, An interesting article by Boomi's CTO just popped up on TechCrunch that touches on many of the ways one can go wrong when creating an API. We're doing well with each of these points, except perhaps rate limiting which doesn't sound like a core concern anyway (rather an extension). Sam The Top 10 Most Common API Pitfalls<http://www.techcrunchit.com/2009/11/08/the-top-10-most-common-api-pitfalls/> *This is post was written by TecCrunchIT guest author Rick Nucci,<http://www.crunchbase.com/person/rick-nucci> the Co-founder and CTO of enterprise integration technology company Boomi.<http://www.crunchbase.com/company/boomi>Prior to forming Boomi Inc., Rick worked for EXE Technologies.* A robust application programming interface (API) has become essential for today’s successful SaaS independent software vendors (ISVs). As a SaaS vendor, you should expect that a majority of your customers are going to require interoperability with other SaaS applications, web services, and legacy systems. As demonstrated by internet pioneers Google, Amazon, and Facebook, an open application strategy facilitates deeper customer usage and enables new revenue streams. Integration is critical for SaaS vendors, and developing a reliable API strategy is the first step toward achieving that goal. Unfortunately, many ISVs still treat their API as an afterthought or merely a “checkbox” on their project list rather than a core feature of their solution. As a result, APIs are not well designed or properly built and wind up costing both the vendor and its customers tens of thousands of dollars in ongoing maintenance due to infrastructure costs and the drain on engineering resources. After reviewing hundreds of actual SaaS APIs, many up to par and others distinctly subpar, it is clear that there are a number of common mistakes made when developing an API. Fortunately, each of them can be easily remedied by following best practices. *1. Exposing operations instead of objects* *Impact:* Bloated call proliferation. By exposing operations, the number of calls your API has to support will balloon up to 4-5 x the number of objects in your application. What’s more, if more than one resource is building your API, there is a bad habit of inconsistent naming conventions, i.e. “addCustomer” and “insertItem” will exist in the same API. *Remedy:* Consider schemas for each object you support, and a common set of actions that can be performed against those objects, i.e. add(), update(), delete(), query(), and of course upsert(). Don’t forget about this often overlooked action, it will significantly reduce the IO against your API because they ‘check for this, then do this’ logic is inside your API tier vs. invoked by the client. This forces all of your developers to follow a consistent set of actions and think about the implications of those actions against a particular object versus designing arbitrary actions against their objects in a vacuum. Following this advice will also drastically improve the readability of your API. *2. Assuming a WSDL contains everything necessary to describe your API* *Impact:* To support the dynamic nature of your API, you either end up doing a blended WSDL/meta data API combination, or you contort and stretch the limits of your WSDL such that most web service toolkits cannot support it. *Remedy:* Keep in mind that WSDL was designed under the assumption that your API call was static, and not multi-tenant. The reality is the majority of your customers are probably customizing their tenant of your app, and those customizations need to appear in real time in your API. This is, from an integration perspective, one of the huge strengths SaaS apps have over their on-premise enterprise competitors. In the on-premise world, the APIs of those applications were either non-existent or at best completely disconnected from any customizations made to the application itself. Consider offering explicit metadata descriptor calls and in these calls return both your base schema for a given object along with any customizations made by the customer back to the user. Try denoting the custom fields with a consistent naming convention, or a dedicated section within each object. *3. Developing a single version of your API which changes with each release of your SaaS application* *Impact:* Your customers get on the “API treadmill” which requires that they repeatedly have to test their integrations with each release of your application. This will inevitably lead to push back from the customer base which may result in pressure to reduce the frequency of your product releases. *Remedy:* Think of your API as a contract between you and your customer. Once you release it, that specific version needs a SLA guaranteeing compatibility to it for some extensive period of time (years). As you release new versions of your application, version your API also. You can include the version number of the API as part of any URL request made against it. *4. Never batching or throttling the results of query calls against your API * *Impact:* Your application performance degrades, resulting in a substandard experience for your API users as well as your web users. You will also likely face unexpected increases in infrastructure costs to support unpredictable demands on your usage. *Remedy:* Put throttling in front of all of your API calls. There are specialists in this area, such as Mashery, that can proxy all of your API calls and enforce this behavior for you. Typically, experts recommend a time based throttle such as X-thousand calls per hour/day. You can also consider charging for additional throttling needs. However, this should not be viewed as a margin-based revenue source and instead should be viewed as a cost-protection revenue source. By charging a premium, you can offset the cost of the existing infrastructure needed to support their requirements. Fortunately, this is also becoming less of an issue due to the advent of elastic computing capabilities a number of cloud providers now offer because your API infrastructure can expand and contract inline with demands. Additionally, for any API call that can return an unpredictable number of results, consider returning those results in pages or groups of some reasonable number, along with a marker that your caller can use to iterate your pages as they see fit. *5. Maintaining separate schemas for adding, updating, or removing your Customer object* * Impact:* Creates the perception of inconsistency and complexity in your API. A Customer, Product, Employee, Invoice, etc. is what it is, regardless if you are adding it, changing it, or removing it. *Remedy:* Have a single schema for each object type. If you do not allow certain fields to be changed in your application once a record has been added, then either throw an error if the users pass in a value for this field (ideal) or ignore the contents of any field that cannot be modified. *6. Forcing the user to specify the data type of fields being passed into your API* *Impact:* You are creating an unnecessary dependency on documentation. And the problem carries forward not just to the initial user of the API, but in the ongoing changes to the underlying schemas that result from customization and product enhancements. * Remedy:* Provide the most relaxed data type restrictions possible and clearly type fields that restrict format patterns, such as a date/time field. An overarching goal when designing your API is to have to write the least amount of documentation possible and instead expose maximum metadata about your API through the use of explicit descriptor calls. *7. Using session-based security in your API* *Impact:* By forcing a session to be created and re-used, things like long running queries need to be contemplated and they are typically not, resulting in sessions being terminated mid-transaction. *Remedy: *Use a standardized sessionless security model like HTTP basic authentication or WS-Security with Username/Password token. Try to avoid implementing a proprietary authentication model like username/password in the SOAP headers or username/password in the body of the data being sent to the application, as this is not discoverable programmatically. Using sessionless security is a convenience for the user as well as provides easier scalability on the server side. This allows requests from the user to be routed to any server in the data center without needing to share sessions between them. Also, by avoiding any login orchestration it is easier to get other websites to access your API so they can do mashups. *8. Not providing a way for your user to know when a record was modified* *Impact:* Your users cannot capture “deltas” or changes to your data over time. This forces them to do bulk extracts out of your application, causing significant inefficiencies and detrimental performance impacts on your application. *Remedy: *Modification tracking is critical any time data in your application needs to be synchronized with another application. This is almost always a requirement with master data, i.e. Customer, Product, Employee, Vendor, etc., as this information is core to your customers’ business and will almost always be represented across all of the key applications they use. By exposing when a record was changed, and who changed it, external processes can capture this information and only extract the changes since the last sync vs. a full extract. *9. Charging extra for your API and not including it for free as part of your offering* *Impact:* An API is never viewed as an “add on” feature by your customer, it is viewed as a “get in the game” feature. In most cases it is needed for parity against your competition, not differentiation. As a result of this expectation, you may end up in an unnecessary and risky negotiation with your prospects. *Remedy:* Make your API free with every edition of your offering. Tout your commitment to openness and encourage your users to explore your API, even during their trial period. You will earn loyalty points with your customer and the message of confidence you exude with this positioning will make you friend vs. foe in the developer community. *10. Getting caught without an API strategy* *Impact:* You are likely losing deals to your competitors and worst case you are not even aware that the lack of API is the reason. You will be perceived as “legacy” and “closed” and “proprietary”. * Remedy:* Beyond the obvious suggestion which is to “build an API!” and from the outset, treat your API as a core part of your product and not an assignment you give the summer intern. Ensure that the API is represented by product management, and put strong resources on the engineering of that API. Consider this: salesforce.com reports that their API gets more traffic than their application! *Conclusion* Unlike the enterprise application era when applications were kept closed and proprietary, the success of today’s SaaS applications depend upon being open and interoperable. ISVs should view their APIs as not just a means of integration but in fact as a way to syndicate their capabilities to a much broader audience – a channel to market as it were. As such, implementing a well conceived and well designed API is arguably as paramount to the success of your business as developing the base application itself. Following the guidelines above should help in maximizing your success as you design, build and implement your API.