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
Jul 27, 2021 Becomes First to Achieve FedRAMP Moderate “In Process” Status for Enterprise Agile Planning Solution

Enterprise Agile Planning, the leading AI-driven DevOps value stream delivery, and ma ...
Read More
Jun 21, 2021

How Agile can be implemented effectively across the organization

Enterprise Agile Planning
Just a few decades ago, a “disruption” was seen as an undesirable thin ...
Read More
May 31, 2021

Agile change management processes are key to delivering software faster

Enterprise Agile Planning
With its emphasis on delivery value faster, agile product management s ...
Read More
May 03, 2021

Bringing the agile planning approach to your whole business

Enterprise Agile Planning
The events of the last 12 months have demonstrated that the only sure ...
Read More
Contact Us