Much of the work I get as an API Evangelist starts with a review of an API area. I have evolved a way to look at API areas, and identify which building blocks are present or missing, all contributing to the success or failure of an API.
I started evolved this methodology in summer of 2012 when I was first building API Evangelist, by reviewing over 250+ of the top APIs out there. I generated a list of the common building blocks used by APIs, as well as identified a bunch of innovative and less commonly used building blocks.
When I first started working with CityGrid I reviewed their API area, which contained the following building blocks:
- API Dashboard
- Documentation for Content and Advertising APIs
- SDKs for iOS and Android
- Version History
- Blog
- Forum(s)
- Terms and Conditions
- Usage Requirements
- Self-Service Registration
I have a list of what I consider essential API area building blocks, and most of them are represented here, but there were a couple missing. So today I added 3 more areas:
An API has to have a getting started page as well as a place for frequently asked questions. Developers have to find the information they need to go from evaluation to integration without asking for help.
The publisher overview page is unique. It covers the different business tiers of developers, or as we call them at CityGrid, publishers. Even though these tiers are unique to how we approach things at CityGrid, they are four potential levels of an API ecosystem, that other API owners can employ.
The CityGrid API area is not up to par 100% by the standards I preach here on API Evangelist. I’m working on a new code samples page which has PHP, Python, Ruby code samples and starter kits--which I will publish this week at some point. But overall the CityGrid API community contains the essential building blocks I feel are necessary to build an ecosystem, and I’m working on finding out what else my developers will need to be successful and put them in my roadmap.
