Developing Programmers .com

I’ve been adding custom fields to our web API at work and thought I’d share some ideas that came up.

1. 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.

2. Make it easy for clients to check the api version. At work, we haven’t even officially published our API yet, but already you can query major & minor version number, we have a policy describing how those change thats useful for people writing interface code, and we have a “checkVersion” method where you tell us what version you want, and we 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.

3. 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?”.

4. 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.

5. 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.

6. 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.

Just to get the word out, in case it helps me with using APIs in the future, I’ll say again: Custom fields. Tell your friends.