We’ve worked with APIs for years at Sparkart, from deep custom SOAP integrations within our apps to many lightweight implementations of Tweets, maps, photostreams, etc. within websites. Today we source content exclusively from APIs rather than directly from a database. In the conventional RESTful API that speaks JSON we’ve found a lingua franca for content on the web. Social media, ecommerce sites, specialized databases, proprietary systems, and even the traditional CMS are all resources that we can leverage in our projects. This has liberated us from monolithic platforms of the past and thereby avoid lock-in, square peg/round hole solutions, and expensive custom app development. Taking such a services-oriented approach with content has come with it’s own challenges however.
Ease of use has been compromised as APIs have steadily matured to address the requirements of mobile apps, privacy concerns, and scalability. Best practices, better documentation, API consoles, and other efforts by API providers have certainly helped to offset this. Complications such as OAuth, field selection/expansion, and variable rate limits continue to stack the deck however, especially against developers lacking experience. Client libraries and social plugins have helped to mitigate the complications, but they in turn compromise creativity. Above all, we’ve found nuanced implementation details to be some of the most frustrating: capitalization of keys, naming conventions, the writing style and even formatting of documentation — it all adds up!
Big API management platforms like Mashery and Apigee, marketplaces like Mashape and APIhub, and focused efforts like Apiary and Swagger have all done a lot to address these problems at the source: the API provider. When there is buy-in and adoption by providers developers win. But too often providers opt to build their own solutions — it is their platform after all. Fragmentation is the natural result. Temboo and Webshell present another direction: curated catalogs of APIs combined with wrappers that normalize supported APIs and expose their functionality as methods. Developers also win here, but only if their desired API and resources are supported. The project of building and maintaining such efforts is immense.
REST clients like cURL, Postman, and Rested are popular tools for exploring and testing APIs before writing any code. This trial and error process takes time but it’s essential to truly understand how to make the right requests to an API. It’s also repetitive — one developer’s experience is at least the nightmare of another somewhere around the world. Valuable insights gained during this process are sometimes blogged, tweeted, posted to StackOverflow, and otherwise shared. But usually they’re forgotten when jumping to implementation. What if we could capture these insights and easily share them with others?
Storyteller.io is an API catalog that grows with every request made using our web-based REST client. When resources are added or updated we evaluate successful requests and save any details that would be valuable to later developers. This could even be you — it only takes a day to forget. Save time and focus your effort on exploring what’s new while effortlessly clearing the path for those who follow. Wikipedia recognized that capturing the world’s knowledge must be an open, collaborative process. We feel the same about mapping the API resources that make the world’s data accessible.
We’re presently focused on cataloging those API resources that provide access to content and other data. Resources that can be accessed with a GET request are all likely candidates. We feel this simplest use case has been increasingly underserved as APIs have expanded to offer far more capability. We’re reviewing new API additions to the catalog daily, one-by-one, to maintain this focus and ensure compatibility with our tools. Simply request an API if you can’t find what you’re looking for.
We look forward to exploring new APIs and resources with you!
