The eight requirements of enterprise API

In this installment, I will write about precautions involved in offering an enterprise-level API. With increased use of APIs in BtoB and other enterprise contexts, taking the following points in mind is sure to help you provide a more user-friendly API.

1. Unified API specs and rules

When each and every API has a varying interface and data format, the result is confusion among users, and your API will see limited use.
While there is no industry standard, recent trends revolve around REST interfaces and data formats in JSON or XML. In addition, a bare minimum of the rules described below in terms of version control and parameter naming conventions should be agreed upon internally before release.

2. Privilege management

Privilege management is extremely important in the element of enterprise API.

Ordinarily, an API assigns one token per user or is based on the premise of use via a single application. However, in an enterprise context, multiple organizations (users) coexist.

For this reason, you must assign CRUD (create, read, update, delete) privileges for each organization and user. For example, members of organization A may be allowed to create data, but they cannot update it. The systems administrator at the company must be able to freely configure these privileges based on actual use.

We will be offering privilege administration functionality starting in September of last year in order to offer a more safe and flexible control of API access.

Click here for information on privilege administration on the IAM API.

3. Logging

While most APIs provide log data on a call level, an API in an enterprise context will need to keep logs on what data was accessed and what functions were performed, both on an API basis and a user basis. This is a must for auditing purposes, and it is critical for exploring the cause of incidents when they occur.

Because APIs often span systems, they may be used in unseen ways, including sudden batch processing at night. This perforce requires logging at a fine-grained level.

4. SLA and maintenance response

While an API functions automatically, this does not mean you can set it and forget it. Further, periodic maintenance will also be practiced. Therefore, the API must have an SLA and built-in responses and rules for maintenance.

In the absence of such agreement, you find cases where services using an API simply return a 500 HTTP status error with no explanation. It is no surprise, then, when concerned e-mails reach the administrator. Implementing thorough error documentation allows the user to respond in the event of a problem.

5. Version control

In an enterprise elements, API updates must be performed in a critical fashion, so manage version control based on a specific set of standards. Ordinarily, a version number is fixed to the API endpoint and new and old versions are distinguished in this way. There may be cases where a system is not equipped to immediately work with the latest bleeding-edge version of an API, so design the structure such that new and old versions can be concurrent, without immediately deprecating old versions.

6. Documentation

There are a surprisingly large number of cases where APIs lack sufficient documentation. While the provider may consider the literature sufficient, putting oneself in the user's shoes, one finds that the information is often totally lacking. It is not enough to simply convey the information accurately -- the documentation must be neither too skimpy nor too robust, and it must be easy to use.

Aim to have your documentation available online. Oftentimes, when setting up a dedicated search server, the result pales in comparison to Google and other search engines, and its usability is lacking. Further, distributing documentation in PDF or similar formats much to be desired in terms of searchability.

7. Libraries/SDKs

Another point equally as important as documentation is your libraries and SDKs. You will not simply be providing an API -- you must also have libraries and SDKs corresponding to various programming languages. You can begin by providing ones tailored to the environments in which you want your users to deploy the API, and then roll out libraries and SDKs for other languages. Corporate systems are not composed of a single language, so you will need many libraries and SDKs.

Taking future maintainability into mind, aim to keep libraries and SDKs thinly wrapped around the API. The point about documentation applies to libraries and SDKs, too, which should have ample literature and sample applications.

8. Sandbox

Lastly, make sure to offer a demo environment for testing the API. Having to immediately update and delete data in a live environment poses too much of a risk to companies. Aim to automatically prep data that is as close to a live environment as possible; ideally, the system should copy data directly from the existing live environment. Being able to test maintenance functionality is also a plus.

API-based development is not complete out of the gate. It is something that is continuously updated and added to. For this reason, sandbox environments should not be limited to 30-day trials and the like, but available persistently.

When expanding use of an API to beyond one's company and offering it publicly in an attempt to foster new business, there are many considerations to make, the above notwithstanding. In particular, when opening up the stores of data accumulated at your company, a level of management commensurate with that data is needed.

It is not simply enough to make the data public -- provide the API only after considering the peripheral technologies and ease of development and use by enterprise users.