Skip to main content
Enterprise Agile Planning Image

This post is from the CollabNet VersionOne blog and has not been updated since the original publish date.

Last Updated Mar 22, 2010 — Enterprise Agile Planning expert

6 Pieces of Advice for API Authors

Enterprise Agile Planning

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.

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

I’ll say again: Custom fields. Tell your friends.

More from the Blog

View more
Apr 08, 2021

Making IT services more agile

Enterprise Agile Planning
The agile revolution completely transformed how we create digital prod ...
Read More
Feb 14, 2021

Reflecting on the 20th anniversary of the Agile Manifesto

Enterprise Agile Planning
Over the past 20 years, it’s been amazing to watch an idea from ...
Read More
Feb 08, 2021

How does agile apply to an entire organization?

Enterprise Agile Planning
Before we dive into the main subject of this blog post, it is importan ...
Read More
Feb 03, 2021

It took a pandemic to realize why digital transformation actually matters

Enterprise Agile Planning
Before anyone had ever heard of COVID-19, businesses across the globe ...
Read More
Contact Us