API Consumer Guide - API Discovery - SLIDEBLAST.COM

API Consumer Guide - API Discovery Prepared By Kin Lane July 2013

API Consumer Guide - API Discovery

Table of Contents Overview of API Discovery API Discovery Building Blocks Companies in the API Discovery Space Tools for API Discovery Finding The APIs You Need

 

Overview of API Discovery In the early days of the web API movement (2005­2010), to find APIs, you went to ProgrammableWeb, which was the only site on the web that was exclusively dedicated to web APIs. Discovery happened via the PW directory and constant stream of news and analysis from across the space. ProgrammableWeb is still relevant in 2013, but as the number of APIs grows, the directory model is not meeting the demand for finding the best of breed APIs that developers are needing to build the next generation of web and mobile apps. Among the API tech sector there is always discussion around the need for programatic discovery in API the API space. Something that uses a WADL­like approach to describing APIs, so that the next generation of API directories, IDEs and other systems can discover, understand, monitor and integrate with APIs­­with less human involvement. In short, this vision hasn't been achieved. While technologists would love for there to be the holy grail of API discovery, in reality the space is taking baby steps from API directories to API hubs or marketplaces where you can not just discover APIs, but interact and even manage API integration and usage. The need for programmatic discovery, and more meaningful indexes of API resources is growing, alongside the growing number of public, but more importantly the number of private APIs.      

 

API Discovery Building Blocks As with other areas of providing and consuming APIs, I'm trying to define the common building blocks of API discovery. Even with the passionate discussions in the API space, there are not that many innovative approaches to enabling API discovery. For years, API discovery is purely about going to ProgrammableWeb and searching through the directory for the API(s) you need. In the last year we've seen new players evolve the paradign with a new API hub or marketplace model, but ultimately there has been no new approaches to empowering developers to find the right API(s).   Here are a few of the common building blocks I am tracking on when it comes to API discovery.

Discovery API Directory ­ ProgrammableWeb is the OG (Original Gangster) when it comes to API directories. API directories allow for submissions and curation of APIs, then enable users to search and browse by keywords and tags. API directories will have their place, much like web, application and other common directories, but will quickly be outpaced by other approaches to API discovery.

API Explorer ­ API Explorers, sometimes called consoles are designed to provide an interactive interface for developers to discover, explore, make calls and see responses in an interactive way. Many API explorers are launched by individual API providers allowing consumers to discover and interact with APIs withi their ecosystem. However a handful of providers also provide this functionality across multiple API providers, enabling a much more discovery style interface in addition to the live, hands­on interaction.

API Hub ­ In the last couple years, we've seen two companies step up to iterate on the API directory model provided by ProgrammableWeb. First Mashape launched with their API marketplace, then in 2012 API hub emerged from software provider Mulesoft. API hubs and marketplaces provide the directory model introduced by ProgrammableWeb, but provide other management and profile tools for both API proviers and consumers. These companies are just getting going, but already offer some very interesting approaches to API discovery that go beyond just finding your API(s).

IDE Extension ­ A new approach to API discovery being developed by the pioneering API providers like Amazon, Google and Ebay is using integrated development environment (IDE) extensions, particularly for Eclipse. These Eclipse extensions or add­ons allow developers to quickly discovery and understand API endpoints. While the current approaches to API discovery using IDE extensions is focused on single provider API discovery, the approach can easily be applied to a wide range of APIs or a particular niche of API endpoints.

 

Companies In The API Discovery Space There are just a handful of companies who are focusing on solving the API discovery problem. We are just moving beyond the directory model, exploring hub and marketplace solutions.  However there are new providers that are focusing on API discovery which is more about integration, testing and monitoring and finding quality APIs.

Apigee Apigee is a provider of API technology and

http://developer.apigee.com/ http://blog.apigee.com/ http://feeds.apigee.com/ApigeeBlog https://twitter.com/Apigee https://github.com/apigee http://crunchbase.com/company/apigee

services for enterprises and developers. Providing a range of solutions from entry level tools for exploring APIs with a console and navigating OAuth, to enterprise tools for managing OAuth, Keys and platform for driving developer adoption while understanding usage, managing traffic and scaling an API platform.  Apigee provides solutions for enterprises like Comcast, GameSpy, TransUnion Interactive, Guardian Life and Constant Contact and thousands of developers use Apigee's technology. Apigee provides resources to help you understand best practices, avoid common pitfalls, develop your strategy, and learn to drive your developer community. Apigee also provides articles, white papers, and other resources to help you deliver your API.

APIhub APIhub is the world's largest API repository, with new APIs added daily. APIhub serves developers and API publishers by providing a powerful publishing and community platform

http://www.apihub.com/ https://twitter.com/apihub https://github.com/apihub

along with consoles and developer tools to insure rapid API adoption. APIhub is a property owned by integration platform provider MuleSoft, who also recently purchased the API directory ProgrammableWeb. APIhub provides API providers with a suite of API management tools, while also being a public API directory, and providing news and trends from the API space.

 

Mashape

http://www.mashape.com/ http://blog.mashape.com/ http://feeds.feedburner.com/MashapesVoice https://twitter.com/mashape https://github.com/Mashape http://crunchbase.com/company/mashape

Mashape provides tools that enable developers to quickly deliver and consume APIs and offers a marketplace for listing APIs.  Mashape provides tools for testing your API, code for generation of custom errors, components for user management and standardized API code language libraries in multiple languages.  Once your API is ready for prime time Mashape provides a marketplace for listing your API, letting developers to easily discover and begin hacking with your API, in a social API community environment.

Mashery Mashery’s API management tools and strategic services help companies connect with customers and partners in a changing digital world by extending reach across devices, markets and the Web. Mashery leads the http://www.mashery.com http://blog.mashery.com/ http://blog.mashery.com/rss.xml https://twitter.com/Mashery https://github.com/mashery http://crunchbase.com/company/mashery

industry with a holistic approach for API initiatives – from setting platform strategy and measuring business objectives to the heavy lifting of providing and managing infrastructure to facilitating relationships with our 150,000 strong network of Web and mobile application developers. Having worked with over 100 leading brands to power more than 40,000 apps, Mashery’s knowledge, experience and proven strategies enable companies to focus on their core business while driving sales, building new revenue channels and realizing faster time­ to­market for innovative applications. Mashery was founded in 2006 and has built an impressive list of over 150 clients that include Best Buy, Netflix, ESPN, Rdio, D&B, Expedia, Klout, USA TODAY and The New York Times.

 

ProgrammableWeb ProgrammableWeb is where you stay in tune with what's new and interesting with mashups, Web 2.0 APIs, and the new Web as Platform. The core of the site is the news blog and the 4 http://api.programmableweb.com

dashboards: Home, Mashups, APIs, and Members. New updates every day, 365 days a

http://blog.programmableweb.com/

year.

http://feeds2.feedburner.com/ProgrammableWeb

ProgrammableWeb was the original public, web API directory, providing a growing directory of

https://twitter.com/programmableweb

APIs that every developer has used to discover

https://github.com/programmableweb

the APIs they are looking for.  

http://crunchbase.com/company/programmableweb

ProgrammableWeb was started in 2005 by John Musser, and sold to Alcatel­Lucent in 2010, then again in 2013 to Mulesoft.  

TheRightAPI TheRightAPI allows you to explore APIs, then evaluate information on each API such as cost, terms of use and documentation­­then share your feedback with the community by rating and commenting on APIs in their registry.

http://www.therightapi.com/ https://twitter.com/rightapi

Developers can try out API usage scenario

https://github.com/theRightAPI

through  test harness or leverage one of the scenarios shared by others in TheRightAPI community. Developers can then automate your tests scenarios to run as often as once a minute or as little as once a day based on your subscription, allowing view of activity through charts, then set alerts of any critical errors.  

Tools For API Discovery There are definitely not enough tools for enabling API providers to offer discovery solutions around their APIs. As we approach 10K public APIs and an untold amount of private APIs, the problem will grow and more tools and solutions will emerge. These are a handful of the tools and services that can be used in API discovery, but unfortunately they are mostly from the perspective of the API provider, which is where the problem lies right now and needs olving by proviers.

Apigee API Console ­ http://apigee.com/docs/consoletogo

Apigee API Consoles make it easier for developers to learn and use an API. You can think of a Console as a "GUI for an API" or "cURL on steroids." Featuring an easy­to­use interface, Apigee API Consoles provide a GUI for exploring an API's resources and executing its methods.

Google API Explorer ­ https://code.google.com/p/google­apis­ explorer/

The Google APIs Explorer allows developers to navigate Google API services, browse available methods, make API requests, and see responses. The Explorer is written in GWT and relies heavily on the Discovery API. By selecting an API you want to explore, you can see all the available methods and parameters along with inline documentation. Just fill out the parameters for the method you want to try and click “Execute”. The Explorer composes the request, executes it, and displays the response in real time. 

 

I/O Docs ­ https://github.com/mashery/iodocs

I/O Docs is a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface. API calls can be executed from this interface, which are then proxied through the I/O Docs server with payload data cleanly formatted (pretty­printed if JSON or XML).

Swagger Core ­ https://github.com/wordnik/swagger­core/wiki

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server.  The documentation of methods, parameters and models can be tightly integrated into the server code, allowing APIs to always stay in sync.

 

Finding The APIs You Need The API discovery research for this paper is much more sparse than my other areas of research. This is a new area I'm tracking on, trying to make sense of what is already happening, and attempt to formulate some thoughts on where things might go­­maybe even stear in a particular direction. I really don't think API discovery is going to be as difficult as many claim it will be. There are some very smart people out there, some who have experience with indexing of the web, and I really don't think indexing and providing discovery layers for APIs will be too big of a challenge. Where I believe the biggest value will come, is in the niche API discovery areas or the long tail of APIs. Discovery for speciality government resources, sensors, commercial fleets and other more obscure areas that the TechCrunches of the world will overlook because they aren't as sexy. In my opinion, API discovery will be half programmatic, with the creation of API resource definitions using tools like Swagger or IO Docs, allowing directories, hubs, marketplaces, IDEs and other discovery layers to find the best available APIs. The other half will be humans verifying that APIs offer value, are usable, reliable and meaningful when being applied to real world situations. Whoever can blend these two approaches, will win. Much like we saw Google dominate with its PageRank, we will also see ranking solutions evolve for API discovery. API discovery ranking algorthms evolved from traditional approaches to SEO and recent approaches to social influence will emerge. There won't be a one­size­fits­all API ranking solution, many will emerge, but they will consolidate as it has done with web and social. This paper will rapidly iterate, as the API discovery arena does. We are close to reaching peak API production, where there are too many APIs available, making proper discovery solutions much more critical.    

 

Appendix A: Curated News and Resources New Feature: Secret Parameter and Headers from h on 5/16/2013), full resource available at HTTP://h 9,000 APIs: Mobile Gets Serious from blog.programmableweb.com on 4/30/2013), full resource available at http://blog.programmableweb.com/2013/04/30/9000­apis­mobile­gets­serious/ List of 16 Sentiment Analysis APIs from blog.mashape.com on 4/23/2013), full resource available at http://blog.mashape.com/post/48757031167/list­of­16­sentiment­analysis­apis Tools to generate beautiful API documentation from www.mattsilverman.com on 2/16/2013), full resource available at http://www.mattsilverman.com/2013/02/tools­to­generate­beautiful­api­ documentation.html