|"You can't fool me, there ain't no sanity clause!"|
It's really slick.
But I Can't Trust ItHere's the problem: It's an un-versioned REST API, and the maintainers don't hesitate to change its behavior between minor releases. Here's what's different between 1.3(2) and 1.3(2)-100:
So, any code based on earlier documentation is now broken when it calls /api/certificate/details.
This Shouldn't HappenDon't take my word for it:
Remember than an API is a published contract between a Server and a Consumer. If you make changes to the Servers API and these changes break backwards compatibility, you will break things for your Consumer and they will resent you for it.
- Renaming fields and/or resource paths – often for clarity after your API is released
- Changing payload structures to accommodate the following: renaming or removing fields (even if they are considered optional – contracts!); changing fields from a single value to a one-to-many relationship (e.g. moving from one email address per account to a list of email addresses for an account)
- Fixing poor choices of HTTP verbs, response codes, or inconsistent design across your API endpoints
It Gets WorseNot only does the API fail to provide consistently formatted responses, it doesn't even provide a way to discover its version. Cisco advised me to scrape the 'show version' CLI output in order to know how to parse the API's responses.
The irony of having to abandon the API for screen scraping in order to ensure API compatibility is almost too much to bear. Lets assume for the moment that I'm willing to do it. Will the regex that finds the API version today still work on tomorrow's release? Do I even know how to parse the version numbers?
What's the version number of the current release anyway?
- 1.3(2)-100 (according to the release notes above)
- 184.108.40.206 (according to show version CLI output)
- 1.3.2 (according to the 'release:' field on the download page)
Would You Use This API?
When I inquired about version-to-version incompatibilities, Cisco's initial response was:
"This definitely shouldn't be happening."
"We are aware of the limitations resulting for not having versioned ASA REST API releases. And as of now there are no plans for us to fix this."Further followed by:
"we will update the documentation to reflect the correct behavior, once we post this fix to CCO."So hey, no problem right? We might sneak breaking changes into the smallest of maintenance releases, but at least we'll document it! Have fun selling and supporting your application!
Clearly I am one of the angry and resentful customers predicted by the articles quoted above :)