This post is from the CollabNet VersionOne blog and has not been updated since the original publish date.
6 Pieces of Advice for API Authors
Over the past two years, I’ve been busy designing and rewriting Codesion’s core systems, all of which have been built around our API layer (XML RPC). Our front-end GUI is driven off our API, as are our provisioning, authentication, and deployment daemons. We have also worked with large customers to integrate their in-house authentication systems with Codesion via our API, and have plans to release a public view later this year.
I’ve been adding custom fields to our web API at work and thought I’d share some ideas that came up.
- Use metadata to automate as much as you reasonably can; eg being able to interrogate an object to find out what calls are available and who may call them is pretty handy.
- Make it easy for clients to check the API version. At Codesion, we haven’t even officially published our API yet, but already you can query major & minor version number, and we have a “checkVersion” method where you tell us what version you want. We even report back whether we are backwards compatible to it. Not hard to do, but get that check into the 3rd party clients early and you can save a lot of headaches.
- Use named parameters and return values. This makes it easy to add a new parameter while remaining backwards compatible. Depending on your programming language, think “dictionaries? maps? hashes?”.
- Don’t design around a particular protocol. SOAP, XMLRPC, JSON, whatever. They’re just wrappers, if you know what data you are sending & receiving you can use any wrapper thats convenient for customers.
- For the sake of customers doing cool stuff, support custom data on key record types. If a customer is doing a mashup and wants to store a twitter ID with a user, for heavens sake let them. My preferred approach is to offer special “get/set custom field” methods, which offer simple name/value pairs that people with API access can set as they wish. Having wished for this feature often in APIs from surprisingly major companies, I made sure we offer it here at work.
- Publish an explanation of your API calls and sample code to help people work them out. Make sure your examples include raw transactions (eg, the xml) in case people have to get an interface working in a language you haven’t covered.
I’ll say again: Custom fields. Tell your friends.