Put simply, a content management software lives or dies on the strength of its APIs. The API-as-afterthought approach might have been possible in the early days of the web, pre-web 2.0 and pre-social Web revolution. Today however, organizations are not “using content management systems out-of-the-box” so much as they are building content-centric apps to fit their specific needs.
In this new, evolving context a content management solution must provide a set of features for reuse and re-purposing. Organizations are under pressure to customize and extend applications to integrate with other Enterprise Applications, as well as with Web services outside of the Enterprise sphere. Gone are the days when a content management solution kept its content in a silo and its users locked into a single experience. Organizations need the flexibility to mash-up content and to make it as well as the app itself available through new channels, whether they be public web, mobile web, or embedded in a productivity app--all of which is itself constantly evolving.
APIs are the key to maintaining your solution’s dynamism, extensibility and flexibility. If you are not convinced, please drop me a line in the comments section, and I will be more than happy to elaborate!
Seeing “API” on a bullet item in a feature list does not cut it. We really need to look under the hood at the details to know whether it passes muster or not. So right away, the quality of the API toolkit comes into play. If it is not transparent enough to evaluate the quality of the API, what will it be like when you get to the development phase of your project! Now, onto the meat and potatoes. What qualities distinguish a good Content Management API from the rest?
First off, let’s refresh our memories. API stands for Application Programming Interface. An API accesses and interacts with the system programmatically, and not through a user interface. So the presence of an API doesn’t necessarily mean anything if you don’t explicitly detail what the API covers in the system.
“Check the API coverage and scope!”
Ultimately, a real content management platform API should offer the full scope of what can be done by a user on the system. I would go so far as to suggest that a Platform (and this might be what separates a content management SYSTEM from a PLATFORM) should offer more through the API. The API should cover everything that MIGHT be needed at some point, while the out-of-the-box user interface offers a simple, economical subset. There is always time to create a new user interface, and if you have an API with the needed features, it’s not necessarily a difficult job!
Unfortunately, today’s Enterprise Content Management solutions are rarely equipped to satisfy this requirement. Most of the time their API implements a mere subset of what the application can do, a fact which in no way prevents them from marketing their API and selling it. Truth be told, this is not specific to content management vendors. Marketing over substance is a general trend the world over!
If you are in the process of choosing an ECM Solution, or if you have one, you are probably familiar with its features. How do you check the coverage of the API of the solution you have, or are currently considering? It’s easy: you are probably already familiar with content management features: create / update / delete; user-management features, work-flow features; advanced features: access audit trail, batch processing, renditions, transformations--whatever the user features, they should be found as much as possible in the API and in its documentation, or else you may encounter scope issues down the road.
“Make sure the software is created around the APIs”
More than the scope, you might want to look at how APIs have been designed.
When the need for APIs became obvious, many software makers tried to add them to an existing solution. Whatever the new technology, simple HTTP, web services, more modern REST APIs, client SDK, and so on, this approach of adding a new layer to accommodate it has always existed--sometimes even on top of the user interface, which would in turn re-purpose the Application features into an API. If you are running a specific, custom enterprise application, and not shipping it as maintained, commercial software, this might be an acceptable approach. But we are talking about distributed, supported, and maintained software that should be expected to evolve!
With a little interest in software design and a dash of good sense, it is easy to see that layering new technologies over an existing solution is not the path to sustainable and maintainable software!
“Can the APIs be extended, and is there good tooling to do so?”
The Nuxeo content management platform is a good example of clean and extensive software design, which has emphasized the role of APIs from the beginning. The platform relies on a content repository and a set of other services which are all made available to a wide range of APIs, including CMIS for the content repository interoperability--a subset of what is doable on the platform. For the broader range of services offered by the platform, the Content Automation API is available, a REST-based API that integrates seamlessly with Nuxeo Studio and Nuxeo IDE tools for developers. The API is extensible, freeing you to define your own API services properly, without hacking.
I believe that is the difference between a platform and a single application. Anybody who offers a platform solution should offer a full range of well-designed, extensible APIs, built at the core of the software. Unfortunately, like many words in our industry, the word Platform has been over-used, and is due for a redefinition.
“You stay ahead of programming technology trends. Your API should, too.”
APIs are not technologically agnostic. They are made in a specific technological context, whether its the programming language, the communication protocol, or in other aspects of their design. When thinking about the underlying technology, you must stay on top of the technology trends, but also be able to sort important new technology that is ready for production from pure hype.
Take remote APIs as an example, traditionally called “Web Services”. There are many paths to follow from the SOAP standard to the REST protocol. Generally speaking SOAP APIs are not as effective as REST-based ones, which is a more recent way to implement remote APIs. REST clearly demonstrated it was more than just hype, and it has been thoroughly adopted by the developer community. This is not always the case however, and never take it for granted that NEW equals BETTER. If we are talking about real libraries and not Web services, an API library (client or server) might be more useful in Java than in Scala, despite the current hype surrounding Scala. The size of the user base of a technology still makes the difference and despite the many promises of languages like Scala, Java is still a major language with a broad set of client libraries available to aid developers!
So a good content management solution should pick good API technology, and in some cases should provide options. For instance, while the CMIS standard offers great value and has demonstrated it can enable interoperability, it is not the best option for all use cases, and it would be an error to rely on it as the sole API for your content management system. The Nuxeo approach has been to offer a full range of functionality through its Content Automation Rest API, as well as CMIS access to the content repository--not one or the other, but both possibilities.
In the same type of thinking, client libraries can be offered in different technologies. In the case of Nuxeo Java, Android, and PHP are covered by Content Automation client APIs. Others can be added thanks to a core API-centric software design. Client APIs simply rely on core APIs, making the system easily extensible.
In conclusion, there should be no doubt about the importance of APIs, and while it’s not difficult to evaluate an API, there is a lot to take into account. However, with a dash of IT-architecture common sense, a general knowledge of the programming technology on offer, a good understanding of content management, and a grasp of the specificities of each case, you should be able to evaluate what will work for you.
Hopefully this article will help IT decision-makers pick a content management platform and software architecture for their content-centric software solutions. And lastly, don’t hesitate to go beyond the reading and analysis. With software, the best approach is always to give it a try, and implement prototypes and proof-of-concept designs. Not all decisions can be made on paper. As true as this is for user interfaces, it holds equally true for APIs.
(comics source: Geek and Poke, thank you for the awesomeness)