BestPracticesforAPIProviders

From MashupCamp

Up: ProposedSessions

Description

Several developer-attendees are interested in the discussion best practices at the API providers when it comes to API/platform stability. This ties to the industrial strength and enterprise readiness question. Based on their experiences in working with the APIs tha are available today, the APIs are apparently subject to sudden changes that sometimes produce unintended consequences. Mashups break as a result and it's sometimes very difficult for a mashup developer to figure out what caused their mashup to suddenly stop working. Are there standard best practices that API providers can conform to? Can API providers and mashup developers work together to codify and maintain a set of best practices (a set that can be hosted here on mashupcamp.com)?

Interested

1. ChrisRadcliff, EVDB
2. JarrodLombardo
3. CindyLu
4. AdrianHolovaty
5. EleanorKruszewski
6. ArnulfHsu
7. FrankHalpin
8. DaveNielsen, StrikeIron
9. ScottMcMullan, JotSpot

Notes from session

Note taker: JeffMarshall

• SOAP vs. REST api - a strong preference for REST amongst participants
• Why even provide different formats for your API? That is, why are some people offering SOAP and REST, etc?
• Example of zEvents case where the SOAP API contained some calls that were different than what was exposed by the REST interface. There's a danger if the APIs are maintained separately.
• iCal vs xCal
• XML parsing can be heavy weight in Javascript -> switching to JSON can provide much improved performance. The point here is that different consumers of the APIs may have different needs, therefore different formats can be useful.
• JSON as a new popular format (some security risks when eval'ing in JavaScript?). JSON is taking off because it can be easily digestible.
• Intermediate proxying of API calls due to cross-domain security issues. Cross domain restriction exists because of firewalling issues; cross-domain requests outside of firewalls should be allowed and might be limiting mashup development (or at the minimum, it's making development more difficult).
• Should proxying be encouraged anyway, to save on bandwidth and hammering of servers?
• Any best pracice lessons learned from current APIs?
• Lesson learned from eBay: With SOAP, define your schema and stick to it.
• Another best practice idea: if supporting multiple response formats, perhaps implement the secondary formats from your primary format (that is, if you initially provide a SOAP interface then build your REST interface with calls to your SOAP interface).
• Which response format should you consider using when you are about to build an API? From Eventful: going with a REST interface allows them to constantly change and add to their API. SOAP would've been more restrictive and required more versioning of the API. However, eBay has found a lot of success with using SOAP at their API core.
• Rolling out new versions of APIs: at some point you might need to version the API if you want to be careful and not break existing API consumers. Incremental changes will often fit within a current API if you are adding parameters or options, but breaking changes need to be dealt with very carefully.
• As an API provider, how do you refactor without angering your consumers? You tend to carry legacy data along with your query responses and tack on the new data. You can try to take this as far as possible until you are forced to clean up and refactor with a [http://www.mashupcamp.com/:/domain/request?ver=2 :/domain/request?ver=2] API.
• Strongly define and design your API at the start before you roll out, as best as you possibly can. In reality you'll need to make changes but you can take the time at the start to try to minimize this. In Eventful's case, their API has completely changed over one year from their initial design. If you are in a space where you'll morph, make sure to minimize your API at the start - don't put in hooks for things you don't have ready yet because you'll guess wrong.
• eBay rolls out new features every two weeks. They build in compatibility levels (versioning) with every rollout. They are on version 447 now, with backwards support to versions 305 and above. They haven't found that XML schema validation of requests doesn't really help them very much. More important is code validating the contents of the request.
• Never assume order in XML! Too many developers are using fragile code (regex's, etc) that can break in ways that it shouldn't when APIs change.
• Best practice for API XML is name/value pair structuring as much as possible. Is there is name for this?
• Rate limiting on your API? Some providers like Eventful don't put any limits on API usage and would love to have their consumers bring down their servers.
• eBay serves up 2 billion API requests per month. There's a massive architecture behind their API to support this. Most of their API usage comes from client apps that are polling data like RSS readers. An architecture that allows the API provider to push data or ping alerts of fresh data would solve a lot of scaling/load issues.
• eBay's call daily limits are very high because they want to foster successful API consumers. They have systems in place to shut down malicious API users, but they find that most often it is buggy client code rather than malicious intent.
• Application keys vs user IDs. Most of the time application IDs are sufficient. eBay is moving to rate limiting on user IDs rather than application IDs.
• For user authentication, provide tokens for account access to protect user account data. If you host multiple services under a single account, you might want to consider giving users a way to enable/disable access to different services.
• Make sure to use HTTPS when dealing with private or secure data.
• What is better when providing an API: fewer calls that are more complex or more calls that are simpler? The response for a simple call like "get me the info for this event" can grow and grow and grow over time as you add in more meta data about the event (like tags, attendees, etc). One solution to this is to make the chunks of data you'll return optional based on parameters to the call.
• Another idea is to offer fine grained data in a single call and optimize for performance based on usage.
• Idea: provide extra data that the API consumer might want based on their query. But in reality, you'll likely want to remove this extra data to give the API consumer faster responses. The decision to include this "bonus" data will be driven by the cost on the API server side to query this data.
• API optimization: is it good to set a rule like "no API call should exceed xxx milliseconds?" This is determined by the use case of your API. For example, eBay has a API query that will send back 20MBs of data...but this is supposed to be a one-time call, and later calls are essentially diff's against this data.
• Error handling: provide an error code and a human-readable string? What about localization? What about classifying errors? Catch-all general errors with a dump that would be useful for debugging when the API consumer sends in a problem report.