API Consumer Guide - API DiscoveryPrepared By Kin Lane

July 2013

API Consumer Guide - API Discovery

Table of ContentsOverview of API DiscoveryAPI Discovery Building BlocksCompanies in the API Discovery SpaceTools for API DiscoveryFinding The APIs You Need

 

In the early days of the web API movement (2005­2010), to find APIs, you went to ProgrammableWeb, which was theonly site on the web that was exclusively dedicated to web APIs. Discovery happened via the PW directory andconstant 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 thedemand for finding the best of breed APIs that developers are needing to build the next generation of web and mobileapps.

Among the API tech sector there is always discussion around the need for programatic discovery in API the APIspace. 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. Inshort, 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 stepsfrom API directories to API hubs or marketplaces where you can not just discover APIs, but interact and even manageAPI integration and usage.

The need for programmatic discovery, and more meaningful indexes of API resources is growing, alongside thegrowing number of public, but more importantly the number of private APIs.  

 

 

 

Overview of API Discovery

As with other areas of providing and consuming APIs, I'm trying to define the common building blocks of APIdiscovery. Even with the passionate discussions in the API space, there are not that many innovative approaches toenabling API discovery.

For years, API discovery is purely about going to ProgrammableWeb and searching through the directory for theAPI(s) you need. In the last year we've seen new players evolve the paradign with a new API hub or marketplacemodel, 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 APIdirectories. API directories allow for submissions and curation of APIs, then enable users tosearch and browse by keywords and tags. API directories will have their place, much likeweb, application and other common directories, but will quickly be outpaced by otherapproaches to API discovery.

API Explorer ­ API Explorers, sometimes called consoles are designed to provide aninteractive interface for developers to discover, explore, make calls and see responses in aninteractive way. Many API explorers are launched by individual API providers allowingconsumers to discover and interact with APIs withi their ecosystem. However a handful ofproviders 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 APIdirectory model provided by ProgrammableWeb. First Mashape launched with their APImarketplace, then in 2012 API hub emerged from software provider Mulesoft. API hubs andmarketplaces provide the directory model introduced by ProgrammableWeb, but provideother 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 beyondjust finding your API(s).

IDE Extension ­ A new approach to API discovery being developed by the pioneering APIproviders 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 IDEextensions is focused on single provider API discovery, the approach can easily be applied to a wide rangeof APIs or a particular niche of API endpoints.

 

API Discovery Building Blocks

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

Apigee

Apigee is a provider of API technology andservices for enterprises and developers.Providing a range of solutions from entry leveltools for exploring APIs with a console andnavigating OAuth, to enterprise tools formanaging OAuth, Keys and platform for drivingdeveloper adoption while understanding usage,managing traffic and scaling an API platform. Apigee provides solutions for enterprises likeComcast, GameSpy, TransUnion Interactive,Guardian Life and Constant Contact andthousands of developers use Apigee'stechnology.

Apigee provides resources to help youunderstand best practices, avoid commonpitfalls, develop your strategy, and learn to driveyour developer community. Apigee alsoprovides articles, white papers, and otherresources to help you deliver your API.

http://www.apihub.com/

https://twitter.com/apihub

https://github.com/apihub

APIhub

APIhub is the world's largest API repository, withnew APIs added daily. APIhub servesdevelopers and API publishers by providing apowerful publishing and community platformalong with consoles and developer tools toinsure rapid API adoption. APIhub is a propertyowned by integration platform providerMuleSoft, who also recently purchased the APIdirectory ProgrammableWeb. APIhub providesAPI providers with a suite of API managementtools, while also being a public API directory,and providing news and trends from the APIspace.

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

 

Companies In The API Discovery Space

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

Mashape provides tools that enable developersto quickly deliver and consume APIs and offersa marketplace for listing APIs.  Mashapeprovides tools for testing your API, code forgeneration of custom errors, components foruser management and standardized API codelanguage libraries in multiple languages.  Onceyour API is ready for prime time Mashapeprovides a marketplace for listing your API,letting developers to easily discover and beginhacking with your API, in a social API communityenvironment.

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

Mashery

Mashery’s API management tools and strategicservices help companies connect withcustomers and partners in a changing digitalworld by extending reach across devices,markets and the Web. Mashery leads theindustry with a holistic approach for APIinitiatives – from setting platform strategy andmeasuring business objectives to the heavylifting of providing and managing infrastructureto facilitating relationships with our 150,000strong network of Web and mobile applicationdevelopers. Having worked with over 100leading brands to power more than 40,000apps, Mashery’s knowledge, experience andproven strategies enable companies to focus ontheir core business while driving sales, buildingnew revenue channels and realizing faster time­to­market for innovative applications.

Mashery was founded in 2006 and has built animpressive list of over 150 clients that includeBest Buy, Netflix, ESPN, Rdio, D&B, Expedia,Klout, USA TODAY and The New York Times.

 

http://api.programmableweb.com

http://blog.programmableweb.com/

http://feeds2.feedburner.com/ProgrammableWeb

https://twitter.com/programmableweb

https://github.com/programmableweb

http://crunchbase.com/company/programmableweb

ProgrammableWeb

ProgrammableWeb is where you stay in tunewith 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 4dashboards: Home, Mashups, APIs, andMembers. New updates every day, 365 days ayear.

ProgrammableWeb was the original public, webAPI directory, providing a growing directory ofAPIs that every developer has used to discoverthe APIs they are looking for.  

ProgrammableWeb was started in 2005 byJohn Musser, and sold to Alcatel­Lucent in2010, then again in 2013 to Mulesoft.  

http://www.therightapi.com/

https://twitter.com/rightapi

https://github.com/theRightAPI

TheRightAPI

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

Developers can try out API usage scenariothrough  test harness or leverage one of thescenarios shared by others in TheRightAPIcommunity. Developers can then automate yourtests scenarios to run as often as once a minuteor as little as once a day based on yoursubscription, allowing view of activity throughcharts, then set alerts of any critical errors.

 

There are definitely not enough tools for enabling API providers to offer discovery solutions around their APIs. As weapproach 10K public APIs and an untold amount of private APIs, the problem will grow and more tools and solutionswill emerge.

These are a handful of the tools and services that can be used in API discovery, but unfortunately they are mostlyfrom 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. Youcan think of a Console as a "GUI for an API" or "cURL on steroids." Featuring aneasy­to­use interface, Apigee API Consoles provide a GUI for exploring an API'sresources 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 Exploreris written in GWT and relies heavily on the Discovery API. By selecting an API youwant to explore, you can see all the available methods and parameters along withinline documentation. Just fill out the parameters for the method you want to tryand click “Execute”. The Explorer composes the request, executes it, and displaysthe response in real time. 

Tools For API Discovery

 

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

I/O Docs is a live interactive documentation system for RESTful web APIs. Bydefining 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 fromthis interface, which are then proxied through the I/O Docs server with payloaddata 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 overarchinggoal of Swagger is to enable client and documentation systems to update at thesame pace as the server.  The documentation of methods, parameters andmodels can be tightly integrated into the server code, allowing APIs to always stayin sync.

 

The API discovery research for this paper is much more sparse than my other areas of research. This is a new areaI'm tracking on, trying to make sense of what is already happening, and attempt to formulate some thoughts on wherethings 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 peopleout there, some who have experience with indexing of the web, and I really don't think indexing and providingdiscovery 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 forspeciality government resources, sensors, commercial fleets and other more obscure areas that the TechCrunches ofthe 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 likeSwagger or IO Docs, allowing directories, hubs, marketplaces, IDEs and other discovery layers to find the bestavailable APIs. The other half will be humans verifying that APIs offer value, are usable, reliable and meaningful whenbeing 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. APIdiscovery ranking algorthms evolved from traditional approaches to SEO and recent approaches to social influencewill emerge. There won't be a one­size­fits­all API ranking solution, many will emerge, but they will consolidate as ithas done with web and social.

This paper will rapidly iterate, as the API discovery arena does. We are close to reaching peak API production, wherethere are too many APIs available, making proper discovery solutions much more critical.  

 

 

Finding The APIs You Need

Appendix A: Curated News and ResourcesNew Feature: Secret Parameter and Headers from h on 5/16/2013), full resource available at HTTP://h9,000 APIs: Mobile Gets Serious from blog.programmableweb.com on 4/30/2013), full resourceavailable 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 athttp://blog.mashape.com/post/48757031167/list­of­16­sentiment­analysis­apisTools to generate beautiful API documentation from www.mattsilverman.com on 2/16/2013), fullresource available at http://www.mattsilverman.com/2013/02/tools­to­generate­beautiful­api­documentation.html