Enterprise architect's guide to API best practices and trends
A comprehensive collection of articles, videos and more, hand-picked by our editors
Ever since programs developed as a collection of components, there's been a focus on the interfaces that bound...
those components, the application program interfaces (APIs). The advent of the Internet and Web services has increased interest in APIs, but it's also revealed that APIs can sometimes limit application flexibility and expandability, defeating much of the benefits of componentized or Web services. The cloud is only going to make API design more important, so architects need to look at a whole new kind of API, based on resources and verbs and not technical dogma, self-defining data models and agility-based design.
API design traps
Many people who look at APIs begin the process by selecting a specific interface model, such as Simple Object Access Protocol or Representational State Transfer. This approach can be useful if there are already other components with which a new API should be linked, but it can lead an architect down a very limited path. A good API looks more at information to be exchanged than at interfaces. To do that, it's best to start with a highly abstract resource-and-verb-based view of an interface before you get into the details of an API.
It's pretty easy to conceptualize any software component as a resource, an element that does something for us. The problem with that very general approach is that it can lead to over-specifying. If you want to expose the functions of a programmable light switch, it's tempting to have verbs like On and Off and maybe status verbs like ReadState. These are nice, but they force an API into being not only functionally specific, but also limited in terms of what technologies can be used to implement it.
The cloud is only going to make API design more important.
The goal of early verb-based consideration is to establish an information or resource model that can be accessed using any convenient program or Web/remote interface. It's important to support the four basic verbs and to avoid adding other verbs that may then restrict the range of interfaces you can use. You might Create a programmable light and then Update its state or Read it, accomplishing the same thing in a more versatile way.
Another trap in API design is the notion of the parameter. If you look at the classical customer record, you can see it contains fields that have to be supported by an API in the form of parameters. What do you really need to know about a customer?
API design practices
If you start thinking of everything you might want to know, the number of customer parameters explodes and the design and development process expands with it. Worse, missing a single piece of customer knowledge can take you back to the design phase, where all the APIs have to be changed to add a new parameter.
A better approach is to think of data elements as self-defining. You create a data structure for an API to pass and the structure isn't rigid, but flexible and expandable. You don't worry too much about whether all the possible data elements are identified up front, because you can simply add one in.
If this is done, there's no need to change every API when a new data element is defined, because there is no specific API parameter associated with a data element. The association is created in the software that processes a request, which is where it belongs. This will insulate APIs from changes in the information model of an application and contain the scope of changes needed to add elements.
The final point in API design is to think of the API in terms of this self-defining model and extend that concept as far as possible into the application components linked with APIs. A browser doesn't have to be programmed to handle an HTML page; it accommodates the data by allowing metadata to be mixed with parametric real data to create a complete process description.
API design and agility
In application design, it's possible to convey metadata and application data co-equally in an API, but also possible to obtain process metadata from a back-end database or other source. If data elements and their associated processes can be defined dynamically, application development is significantly more Agile.
It's possible to extend this self-defining agility from the API into application components themselves. Traditionally, programs are authored to process specific data elements, but with metadata advances it's possible to use expressions coded as metadata to describe even complex processes. That means complete applications could be developed using extensible data and metadata models, significantly reducing the time needed to respond to new business problems or opportunities.
This level of agility is exceptionally useful in applications that don't confront large volumes of transactions, but the overhead associated with it may be excessive for some mission-critical tasks. Thus, it may be best to mix traditional logic to process data elements that are almost always present or require considerable processing, and use metadata descriptions for less frequently used data. In all cases, though, the APIs can be designed to pass data and process metadata as needed.
The term "agility" has become almost a cliché in technology, but there's a reason for it. Opportunities have to be addressed in their own time, and applications and APIs have to conform to that business-based schedule. Rethinking API design can make your own applications better, more Agile and more cloud-ready.
About the author:
Tom Nolle is president of CIMI Corp., a strategic consulting firm specializing in telecommunications and data communications since 1982.