Posted on March 8, 2012
APIs are great! Every developer you talk to will usually say that an API is the preferred way to go when you want to talk to other systems. Now ask that developer if they like working with APIs. Specifically, other peoples’ APIs. They will normally answer ‘if….’ otherwise – no! I’ve both built and integrated with 3rd party APIs and I have to say, it’s actually one of my favourite elements of software development. However, some APIs drive me very close to a whole load of crazy induced by what can only be described as a whole parade of stupid. Error codes that say the same thing for every error – *scream*! Language or library specific integration – *scream*! Terrible or non existent documentation – *scream*!
I could go on….
There seems to me to be a strong need for an API etiquette document so that all developers can successfully integrate with each other, a big money spinner in lots of technology companies. Let’s look at some basic points that would make an integration a whole lot more seamless.
Documentation should be entirely representational of your system and its interactions. If you’ve built one of my favourite types of system, you should have documentation that covers every component that has a public interface or is extended to from a component with a public interface. In my view, documentation should include and not be restricted to:
- Error codes and their definitions
- Links to online docblock documentation
- Examples in main languages for common transactions
- Contact information to a technical department for support
- Change list for the last at least 3 versions (if they indeed existed)
- Web Services that are supported and examples of connection
But be careful not to waffle. Waffling documentation will often contain complex stories that are rarely updated, let’s face it – would you want to update that documentation? It will also contain little or no easy to find points of reference for ease of use. Your documentation should resemble a well formed map. You should be able to quickly navigate, understand and implement.
Web Service Support
Web services are usually key to accessing an API. The most popular being REST and Soap. There are others available to you, but these are the most popular right now. There are a few short guidelines that in my opinion, should be key when making decisions about what you support.
- Don’t restrict users too much
- If possible cater for at least 2 types of web service interaction. What’s best for your system may not be best for others. REST or Soap are usually suitable for most
- Do not expect users to rewrite systems to accommodate little used libraries unless absolutely necessary. They can just use another provider’s API….
- Make sure each transaction is secure, this is your responsibility to make sure that you are 100% secure.
Your system should never require specific platform alterations from a 3rd party to accommodate your system outside of web services. If you require specific functionality to be present either side, you’re not doing it right. APIs promote SOA (Service Oriented Architecture) and should rely on service alone.
Comprehensive Error Support
One of the most frustrating things I have found when integrating with APIs, is the lack of proper error handling. The amount of times that I have received ‘Soap Exception’ for every error in an API or ‘Something went wrong, contact us’ still causes me some concern when I encounter them. It shows me that irresponsible developers have built the system. Whether that is actually the case or not, my trust in that API is drastically reduced at that point. Errors should have useful descriptions at the very least and this is even more important if you are including parameters with your transactions. I prefer the use of codes, they are easy to look up in the documentation that ‘should’ include them. They are also very easy to communicate to the technical people at the other end to investigate or support as each code of error in any area of code should be unique. You can then pinpoint EXACTLY where it broke down. That saves so much time! Time is money….. for both parties.
Without this, your integration may never be error free or your development team quick in a response of transaction failure.
During integration, there should always be a technical support contact. Ok your developers most likely don’t want to be interrupted constantly by 100s of other developers with questions about the API, however, there should always be a team that are dedicated to this type of support. That team should be completely conversant with the API and should have a deep technical knowledge to be able to understand queries. These people should have documentation themselves that provides them quick reference to error scenarios (the codes and descriptions with likely scenarios that can be a living document is best) to help other developers. Personally, I have been known to refuse to continue development without this, especially if other elements of this post have been ignored, such as documentation. It’s an extreme reaction, but developing blind will never work out well. Better to gather the right information and tools first.
If you’re the developer lucky enough to be building and API, you will most likely be extending functionality that is already written and building a layer for 3rd parties to use your system. Your main focal points to remember should be:
- What can I reuse?
- If I go directly to that functionality, can the system be compromised?
- What security measure should I be looking at in order to reuse?
- Do I need to develop new functionality? Why? Is it really API specific? If not, it’s actually 2 or more projects there that should be treated accordingly as such.
- Are we handling errors correctly and comprehensively? If not, how can I make this work for 3rd parties while always enhancing the system.
- Can I expand with what I’ve planned?
This list is not exhaustive, there are always more questions to ask. This list however answered correctly, will give you a great stepping stone on extending your system for 3rd party access.
All in all, follow these simple etiquette guidelines and you will find your API not only flies, but other people will actually want to work with it! Without this, expect lengthily support for 3rd party users which wastes not only your time, but theirs. With this, everyone should be shouting ‘I HEART APIs!!!’ instead of looking like that chap up the top there. Simples!