Posted on 02-02-2013
When I talk about API discovery, in-person at events, or on my blog(s), I notice people automatically default to thinking I mean a universal API discovery language that will work for all web APIs. I think the technologists that operate in the API space are always striving for technical perfection--resulting in the discussions that you see around REST, HATEOAS, OAuth and similarly for this one about API discovery.
I’m thankful for the passion and dedication of the technologists in this space, but when it comes to API discovery, I’m never talking about a universal language or approach. I personally just don’t believe there can be one definition to rule them all. When I reference API discovery, I’m focusing on API discovery at the provider level, and providing information and resources that allow people who launch APIs to be successful. I have no interest in defining or support a world-wide or industry level definition for API discovery. I leave these conversations to all y'all tech pundits.
I am a fan of supporting API providers to do something, anything! Sure, it should be a standardized as you feel necessary. I hope you use something that is already in existence like WADL, Swagger or I/O Docs (don’t reinvent the wheel), and make sure and look at the approach Google is taking with their API discovery service--as they have some experience in the field.
In reality though, your motivation to develop JSON or XML definitions for your API will probably be to provide interactive documentation or allow for easy generation of code libraries for your API--not discovery. With the API discovery conversation automatically defaulting to a universal definition by the tech pundits, API providers will often avoid these discussions, leaving it a lower priority when planning and implementing an API. Much like with HATEOAS, without concrete examples of value, API providers won’t see value in providing JSON or XML definitions of their APIs. Interactive docs and auto generation of code libraries are clear value propositions, and show potential for bringing discovery back to the forefront.
Once you have API definitions for all of your API endpoints, its pretty easy to publish a single manifest of all of your APIs in a single JSON (or XML) file in the root of your developer area. Sure I would love all of these definitions to be the same, but I prefer a more pragmatic approach and will accept whatever a API service provider deems suitable for their APIs, and with the resources they have available.
If you think about how web page discovery came together in late 1990s with Yahoo, then solutions provided by Google, and even new approaches from providers like DuckDuckGo. When it comes to API search and discovery, we are in circa 1997, if we compare it with web page discovery. You have directories like ProgrammableWeb, but you also have newer vendors emerging like APIhub, who potentially bring a new perspective to the table.
Since APIs are about “programmatic discovery”, I think how developers discover API will vary, occuring via these directories and hubs, but also occur via their chosen PaaS platform like Drupal, Heroku, Salesforce or with BaaS providers like Parse or Kinvey--as well as popular IDEs like Eclipse who allow for plugins.
It will up to PaaS, BaaS or other 3rd party platform providers to assemble resource stacks that are meaningful to their community. They will do the legwork to find best of breed API resources, which will be made easier if API providers provider JSON or XML definitions of their API resources, but not a requirement.
I believe that similar to website sitemaps, API discovery will have wider definitions that some follow, with successful vendor specific implementations as well, but ultimately it will remain largely imperfect and some API providers will do well, and others will implement poorly. The markets will decide! (cringe)
My object is to help the average API provider hear stories of other successful approaches, and identify the benefits, in hopes that they will implement something, anything! Allowing us to take baby steps forward in API discovery, not defining one definition to rule them all and nobody giving a shit, and we don't move forward at all.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- What I Have Been Calling API Trends, Are Slowly Being Baked Into API Operations
- FDA Finding Their API Mojo With A New Drug Label API
- Adding PokitDok To Healthcare Research And The API Stack (Well They Did)
- Why I Am Continuing To Integrate Zapier In My Business Workflow
- Who Is Going To Build The Uber API Platform For The Sharing Economy?
- The API Focused Dev Shop
- Route SMS Messages To Google Spreadsheets Via Twilio API With TwilioSheet
- Publishing Your APIs To Product Hunt
- Providing Users With Reciprocity Tools So Important Intuit Purchases itDuzzit
- Bing Developer Assistant for Visual Studio Delivers Relevant API Code
- Average Number of APIs Used In A Modern App
- An APIs.json Collection Of API Resources Across Your Public, Partner Or Internal Resources
- One Possible Reboot Of The API Stack
- How Are Dev Shops In Chicago Using APIs? A Talk With Bryson Pouw At Blaze Portfolio
- Every API Provider Should Have A Logo And Branding Page
- What Is An API First Strategy? IT architecture And Catalyst For Engagement
- The Speed Of Federal Government When It Runs On Github
- Swagger, APIs.json, And Review For The New Developer.Trade.gov
- Student, Instructor, Classroom, Class, And Course API Planning At BYU
- Can You Add My API To Your Website Listing?
- Adding Google To List Of API Deployment Companies
- What Is An API First Strategy? Adding Some Dimensions To This New Question
- The Five Month Journey Toward A Stable APIs.json Discovery Format
- How Are Mobile Dev Shops In Chicago Using APIs? A Talk With Dave Devitt At SYDCON
- An API Case Study Format From Google Cloud Platform