Open API structure requirements 101.

When creating an API for consumption by another system or systems, there are certain things I like API’s to do and also some assumptions that really should not be made. As I have done quite a few API of this nature I decided to document just a few things I try to do and also try to avoid doing.

As always, I will update this list with information based upon feedback should I get any ^^.

What an API should enable or be able to do:

• An API should be able to be plugged into any system and start to show it’s benefits
• An API should not conflict with an existing API or the system it is integrated in, if at all possible
• An API should document its REAL dependencies and requirements at a processing CPU/Memory level and also at database/network/disk space resource usage level.
• An API should also be able to produce Metrics on its operation and its environment
• An API should have Multi-threaded or Parallel processing where possible to enhance performance
• An API should be easily upgradable
• An API should be easily extended (usually via logic/rule engines, or plug-in architectures).
• An API should have logs/audits/performance-checks that can be disabled or enabled (when enabled performance will drop of course)
• An API should be documented with Unit tests and examples showing how it can be used.
• An API should where possible keep the same API signatures and objects backward compatible with previous versions of the API. (this is quite hard to do, but there are guidelines on depreciating old signatures with new ones, by introducing a new signature and flagging an old one as redundant and legacy, and then a release or two later removing the old signature)
• An API doe’s not need to reveal exactly how it does what it does in fine detail unless that was agreed in it’s design. (normally this is IP and NDA protected in most companies, although most of the time the technologies already exist in various forms already… very few new idea’s on data processing or system processing these days, just better tools that promote slightly different ways of doing things.)

What an API should never Assume:

1. It is responsible for exception management
   1. Error reporting, etc.
2. It will never have functional parts of its operation replaced
   1. Logging,
   2. error systems,
   3. UI aspects,
   4. Even processing logic (Ideally this should be done in such a way that it can be extended easily if at all possible, rule/logic engines allow this, and I will blog on rule/logic engine creation at a later date.)
3. It will never have its API syntax changed