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.
|API Discovery, Directory, Hub, Search|
blog comments powered by Disqus
Latest Blog Posts
- APIs in DFW
- Adding API Broker Under Monitoring for API Aggregators
- The Dark Matter That Make APIs Work
- Potential for API Aggregators to Provide Valuable Industry Data
- My Talk Tomorrow Night at the Dallas-Forth Worth API Professionals Meetup
- The White House Releases An Open Data Strategy
- When API Success Signals Begin Working Against You
- Get To Know Which Languages Your API Developers Are Using
- Twitters Developer Area is More Embeddable Than API
- Overview Of Backend as a Service (BaaS) White Paper
- Make Sure And Have Multiple KPIs For Your APIs
- API Enabled Toys For Our Children
- I Am Speaking At The Dallas-Forth Worth API Professionals Meetup May 14th
- How Much Do You Spend Attracting and Supporting Freemium API Developers?
- What Does The API Evangelist Do?
- Startups Need To Work Together on API Definitions
- Parse Is Successful By Truly Solving Problems for Mobile Developers
- API Commandment: Thou Shalt Not Forego Talking to a Person
- API Trends
- API Priorities
- Have You Taken A Look At AT&T APis Lately?
- Helping People Understand APIs Through Real World Examples
- Evolving Beyond API Service Providers and Tools to Goal Based API Toolkits
- APIs & The Federal Government
- After Last Couple of Weeks, It's Clear There Is Big Opportunity In The API Space