In a world of interactive componentized software, there's nothing more important than the application program interfaces(APIs) used to link components with each other, mobile devices and browsers. Build an API the right way and it helps assure functional integration and developer loyalty; do it the wrong way and compromise an entire project.
There are three ways to help get on the right side of API building:
Address component architecture and binding framework; and
Ensure changes are handled gracefully.
APIs expose features and services to developers. The way an API is used and the spectrum of services represented is the primary design driver. One of the most significant mistakes developers and architects make in API building is ignoring a constituency. It's vital an API design be a good fit in the ecosystem of developers, languages and other APIs.
Common API design issues
The REST versus SOAP debate is an example of a constraint set for APIs. Where applications already depend on one or the other, new APIs should obviously conform. Less obvious is that most APIs are part of a trend toward componentization and exposure of features. The movement may take a set of APIs more in a REST or SOAP direction over time, so be sure to anticipate that migration.
API build problems will destroy an application faster and more thoroughly than almost any other type of architecting error.
Architects can easily be bitten by conforming to object architecture and binding framework. Picking the right API design is important because it's difficult for developers to use an interface that doesn't match the architecture of the applications they're building. It should be noted that RESTful APIs typically represent resources whereas SOAP APIs represent remote processes or procedures.
Some protocol is likely used to bind APIs to API users and with Web applications, which are typically Hypertext Transfer Protocol (HTTP)/ HTTPS. Using HTTP with a Hypertext Markup Language or Extensible Markup Language (XML) data format, or JavaScript Object Notation (JSON) and JavaScript on client devices, makes it easy to create graphical user interfaces from an API but may not be appropriate where browser access isn't the application's intention. Some applications and APIs may use a specific Transmission Control Protocol or User Datagram Protocol port rather than Web port 80. While this can help to keep API traffic separate from Web activity, it may have firewall/security implications that will demand special system configuration that either exposes the APIs or uses them remotely.
General API design rules
Most APIs can be viewed as syntax of verbs and nouns. For example, a sentence with a verb representing a requested action (get, put, delete) and the nouns signify arguments appropriate to the action. It's good practice to always generate a status/result variable that communicates error conditions or successful execution. The error conditions should be comprehensive enough to communicate problems unambiguously.
The semantics of the API, meaning the syntax of the functions provided, are important because the ability of the API to convey its services and parameters clearly reduces developer errors. One critical point is that if the API represents a stateful service, the function semantics should be session-oriented (find-record, update-record, delete-record) where the stateful nature of the service is made clear.
It follows that if, as in this example, the update and delete functions operate on the previously located data element, then the update and delete functions do not supply their own data element keys; they'd be redundant and risk generating developer confusion. On the other hand, a stateless service must always provide all of the data since no session context could be inferred.
Common questions and issues
Syntax issues created by updates or changes to the API are often ignored. There are two sides to each API and the change process can pull them out of synchrony. Some architects will express a version variable in an API to ensure that both sides are expecting the same formats. At minimum, both the server and client side of an API should perform basic validation to protect against changes that create a mismatch of syntax so they don't contaminate information or crash applications.
Another common question has to do with the data format. XML is the most general way of expressing parameters and exchanging information, and it is applicable to REST and SOAP interfaces. But XML processing is a heavyweight and most valuable for expressing structureless data. For REST, JSON has gained favor as being easier to use while providing some specific variable typing widely used and expected in API building. Where APIs exchange rigidly defined data elements, JSON is likely a better choice for RESTful exchanges.
API testing is often lumped into application lifecycle management processes. Some of it rightfully belongs there, but there should also be specific unit-test processes designed to validate APIs and establish that they'll perform gracefully even when data includes errors. The looser the data binding and typing of an API, the more risk there is of passing information that will result in a later error or crash. This is why it's important to adopt tight constraints on variables and to test each API with a range of data.
API build problems will destroy an application faster and more thoroughly than almost any other type of architecting error. Spending more time designing APIs to anticipate current error conditions and future changes will be time well spent.
About the author: Tom Nolle is president of CIMI Corp., a strategic consulting firm specializing in telecommunications and data communications since 1982.
