{"API Getting Started"}

The Open Guide to Amazon Web Services

I keep an eye on things that are trending daily and weekly on Github because it is a great way to discover new companies and individuals doing interesting things with APIs. While looking at this earlier this week I came across the open guide to Amazon Web Services, a pretty robust, and well organized getting started guide to everything AWS.

Here is their description of this resource out of the leading cloud computing platform:

A lot of information on AWS is already written. Most people learn AWS by reading a blog or a “getting started guide” and referring to the standard AWS references. Nonetheless, trustworthy and practical information and recommendations aren’t easy to come by. AWS’s own documentation is a great but sprawling resource few have time to read fully, and it doesn’t include anything but official facts, so omits experiences of engineers. The information in blogs or Stack Overflow is also not consistently up to date.

This guide is by and for engineers who use AWS. It aims to be a useful, living reference that consolidates links, tips, gotchas, and best practices. It arose from discussion and editing over beers by several engineers who have used AWS extensively.

I find it interesting when API providers invest in authoritative solutions like this, acknowledging the scattered and often out of date nature of blogs, QA sites, forums, and the wealth of other self-service resources available for APIs. Amazon is getting seriously organized with their approach to provider resources for developers--they have been doing this a while, and know where the pain points are. 

Amazon's organized approach, the breaking down by service, and the usage of Github are all interesting things I think are worth noting as part of my research. AWS is a tough API pioneer to showcase because they have way more resources than the average API provider, but as one of the early leaders in the API space they possess some serious wisdom and practices that are worth emulating. I'll keep going through their open guide, and see what other patterns I can extract and showcase so that my readers can consider.

See The Full Blog Post

A More Distilled Version of An API Getting Started Page On The Home Page Of A Developer Portal

As I look through API portals, profiling the building blocks of successful API platform, I'm always looking for bite-size stories for my readers. I was working to complete my Instagram API definition, as part of my photo API research, and their getting started graphic caught my attention.

This three step getting started visual for Instagram is prominently available on the home page, providing a very distilled down version of what I recommend API providers usually accomplish with a dedicated getting started page.

The featured getting started area provides you with the link to register your application, and overview on authentication and authorization, and a link to all the endpoints, so you can start making requests. I am a big fan of there always being a dedicated getting started page for APIs that I am on-boarding with, but I am always a bigger fan when someone distills these building blocks into something that is way easier to understand, and execute--without all the blah blah blah.

I'm going to consider adding a feature getting started building block, in addition to having the dedicated page. When done right, I think they can accomplsh the same thing, but with one less click--reducing any friction we possibly can in the on-boarding process.

See The Full Blog Post

Brewing Up Something Awesome With The Jive Software API

Enterprise social API Jive Software wins for the best developer landing page. Normally I tell folks, like I did with Trade.gov last week, that your landing page should have a short, precise description of what you API does—this is some seriously valuable real estate, and you have one chance to make an impression.

I would put Jive Software into the category of more making a first impression, than providing a short description of what the API does:

I wouldn’t recommend this approach for every API provider, but if you can do it right, and make a solid first impression—run with it! As an API Evangelist, and IPA Evangelist, I can seriously get behind a message like “brew up something awesome”. +1

I like how they have apps, docs, APIs, and IPAs as taps, and the taps even work when you mouseover! Seriously, all of this API shit is hard to make entertaining (trust me I know), and when you can provide this human touches while inciting innovation, they can go a long way in breaking the ice with consumers.

Right above the taps Jive Software provides the essential getting started, and register links for their APIs, which signals that beyond the fun facade, they mean business, and want to help you onboard with using their APIs. I haven’t dug deep into the Jive Software API to see what else is going on, but after this first impression it is likely I will be looking around more, now that they made a good first impression.

See The Full Blog Post

A Simple, Honest Approach to Getting Started With The Marvel Comics API

I’m currently reviewing the Marvel Comics API, and their approach to making their rich content available via a simple web API.

They did a great job deploying the API. To start with they published very simple and honest getting started steps:

  • Sign Up - Get an API key
  • Be A Good API Citizen - Read, understand, and abide by the terms of use for the Marvel Comics API
  • Link Back - Observe the attribution and linking guidelines when displaying data from the API
  • Keep In Touch - Tell us about what you're building and talk to other developers on our community page
  • Build Cool Stuff!

I like their style. As a building block, getting started pages are pretty important, yet most API providers provide very dry, technical steps for on-boarding with an API—if at all.

The Marvel Comics API is a refreshing approach to explaining to developers how to get up and running with the API. Its nice to see from such a big brand.

See The Full Blog Post

Baseline for Federal Government Open Data and API Portals

I have a whole list of projects around open data and APIs at the Department of Veterans Affairs (VA). Additionally I have numerous other open data and API projects I'd like to tackle across other federal agencies. As I do with other areas of my work, I needed a standardized way to stabilize the datasets and APis I will need for my projects, in the same way any open data and API provider should do for their consumers.

To help support my work, and hopefully the work of others I wanted to create a baseline portal that I could use at the VA, for showing what is possible when hanging open datasets and APIs, in a full featured portal. The success of any open data and / or API portal starts with the technical building blocks, like data and APIs, but have a set of business and political building blocks that are essential to their adoption and growth.

I've spent the last three years studying the business and politics of APIs. During these three years I've looked at almost 10,000 API developer portals, and I've established a base set of what I consider the building blocks of successful API portals, with a handful in which I consider essential to success. I've always wanted a simple API portal template that would reflect this research, and my new Developer @ VA portal is the first step towards achieving this.

Developer @ VA is an early stage prototype, whcih I've built to satisfy this need of mine, specifically for my VA projects. I will be polishing this portal and replicating it as a single template that can be used for any API and / or open data portal. This portal exists purely as a Github repository and runs on Github Pages, using a Jekyll for managing its pages and blog. Everything else is HTML, CSS, Javascript and JSON, allowing it to be able to run on any server, including other cloud services like Dropbox or Amazon S3.

To start with I've included 20 of what I consider essential API building blocks:

  • Landing Page
  • Getting Started
  • APIs
  • Data
  • Interactive Docs
  • Code
  • Gallery
  • Support
    • Self-Service
      • Stack Exchange
      • Quora
    • Direct Support
      • Issue Management
      • Twitter
      • LinkedIn
      • Facebook
      • Google+
  • Roadmap
  • Changelog
  • Blog
  • Terms of Use
  • Privacy Policy
  • Branding Guidelines

Beyond this project running using open formats and standards, and being deployable in common cloud environments like Github, Dropbox and Amazon S3, everything is machine readable by default. The portal starts with a sitemap.json, which links  to other building blocks that make up the open data and API portal, including a data.json and api.json which provide programmatic access to all resources included in the site:

  • data.json - Machine readable JSON file of all data assets using common core metadata for easy access to all data stored in the portal
  • api.json - Machine readable JSON, using the Swagger format describing all API resources available within the portal

Next I wanted all essential building blocks of the portal to also be machine readable by default:

  • Code - JSON library of all code available for use when integrating with datasets and APIs
  • Gallery - A JSON gallery of web, mobile apps and visualizations, widgets, excel and other integrations on data and APis
  • Support - A JSON listing of self-service and direct support channels for the portal
  • Roadmap - JSON listings of both the future with a roadmap, providing transparency into portal operations
  • Changelog - A JSON listing documenting the past with all changes made to the portal
  • Legal - A directory of the legal building blocks of the portal with links to terms of use, privacy and branding guidelines

This project is the product of 3 years of research, and 3 days worth of work. So it is rough. I was able to capture my initial vision in 3 days, but still a lot of work to do. I need to let it simmer a little bit, and round off some of the rough edges and apply some polish. Then the next step is to generate a generic template from it, that will become the baseline for any other portal I derive from this work.

If there is anything you'd like to see in the future, go ahead and use any of the support channels available on the site. Once I get the base template set up, I will use that as a top level project to guide the future of this baseline for open data and API portals.

See The Full Blog Post

I Like Individually Priced API Resources That Flex and Scale

On a regular basis I review my API consumption to evaluate how I’m using various APIs, and what I’m paying for them. I depend on around 20 APIs to make API Evangelist work, and I need to make sure I’m using them to their fullest potential while also being mindful of budget.

As a part of my regular review, I am looking at the differences in pricing between three key services:

  • FullContact API - I use FullContact for all my company and individual contact intelligence. I go through phases of light or heavy use depending on research projects I have going on. Full Contact provides me with per API call rates depending on the endpoint and call volume, and they limit me between four packages Trying It out (Free), Getting Started ($19/month), Gaining Traction ($99/month) and Rolling ($499/month)
  • Alchemy API - I use Alchemy API to primarily pull text content from blog posts, so I can use it internally for indexing. With Alchemy I get access to three packages Free, Small Business ($250.00) and Basic ($800.00)
  • AWS APIs - I use AWS for all my computer, storage, database and DNS API services. With AWS I pay by the resource, bandwidth transfer and storage and the other parts and pieces or specific actions in cloud computing. There are no packages, just modular API resources I use and get billed for.

I’m just one use case, but figured I’d share my thoughts on how I use these three API resources within my little world.

For Full Contact the jump from $19/month to $99/month isn’t too bad. I’ll lump all my processing together into a single month and get lots of work done. So I tend to toggle each month between these two tiers based upon my needs.

For Alchemy API I operate within the free tier and stick with the rate limit of 1,000 API calls per day. If a blog post doesn’t get pulled because I hit my limit, I queue it for another day when I have room within my daily limit. The jump from zero to $250.00 / month is really just too big of a jump for me to make.

My Amazon Web Services bill runs between $250.00 and $1,000.00 / month. Depending on how much traffic, harvesting, processing and other crazy stuff I’m doing. I have a buffet of compute, storage, database, IP address, monitoring,DNS and other cloud computing modules that I have developed and associated with pricing in my head, so that I can make decisions in the moment about whether I can afford to process a bunch of data, launch new API, website etc.

I have a few good friends in the API space that feel API rate limits stimulate creativity, innovation and work-arounds. I agree with that statement, and think every API has to understand its own consumer and make the decision they feel is best. But in the end, I personally like single API resource pricing based upon units, that I can scale infinitely as needed in any moment. I’m am more likely to integrate services into my world when they are independent bite size chunks, with pricing not restricted by other services or service tiers. Each module tends to have different value in my world and I like to make independent decisions about how to use just that resource, disconnected from all the other resources.

The world is starting to look different when I depend on 10-20 APIs vs 1-2 APIs, and I can imagine when I reach the point where I'm depending on 100-200 APIs I will have an even greater need to have API resources be priced independent of other services or limiting pricing tiers.  

See The Full Blog Post

Self Service vs Sales Oriented Web APIs

I’m doing some big data work. Ok it isn’t really, but feels like I should use that label. What I’m actually doing is analyzing the Twitter activity of top APIs.

I have the twitter handles of 100 of the popular web APIs. I have been pulling and analyzing the Tweets from each of these accounts via the Twitter API for some time now.

It is time that I scale this to about 500 API twitter accounts, and also start monitoring mentions of each of these APIs on Twitte, while also performing searches for some keywords associated with each API or a group of APIs.

At this stage of growth, it was clear I was outgrowing the regular Twitter API and since what I’m doing is more big data, than twitter client app, I am looking at the two approved Twitter resellers Gnip and Datasift.

First I went to Gnip, looked at their product and it looked like what I needed. I saw at the bottom of the page, “Get Started”. I recognize that language, clicked on it and filled out their form and I get a “Thank You, Someone Will Be In Touch”.

Ok...so I move on to Datasift. I look at their product and it too, looks like what I need. I see on the page, “Get Started”. I recognize that language, clicked on it, logged on with Twitter, added my email and password, and boom--I’m dropped into a dashboard. I am able to build streams from Twitter using different keywords, Twitter users, etc. I get freemium access, with the ability to put in my credit card and be billed for more.

Next, I got a quick email from a nice fellow at Gnip asking what I was looking to do, and if I had time in the next couple days to talk on the phone.  I will definitely talk with them, but by the time I get on the phone with them I will be 2-3 days into developing my solution around Datasift. Unless Gnip has some secret pricing or some magic features Datasift doesn’t have, I probably won’t switch.

That’s the difference between self service and sales oriented web APIs. Which one are you?

See The Full Blog Post

Will a Self-Service API Area Ever be Enough?

One of the essential ingredients of a successful API, is a self-service area to support your API developers. In my opinion this is a no-brainer. You have to have registration, documentation, code samples, forum and other essential API building blocks available to developers in a self-service way--so they can engage with your API 24/7 without asking for access.

I’ve worked hard to make sure the CityGrid API area has a logical navigation, taking developers to the essential information they will need to learn about and integrate with the APIs:

With those 13 links you can get to everything you need to know about the CityGrid Places, Offers, Reviews and Mobile, Web and Custom Advertising APIs.

I keep a regular flow of information going through the blog to make sure there is excellent SEO content, so developers can search for anything at Google, and the blog will support linking to whats relevant in the CityGrid Developer Center.

Even with all of this, I still get some pretty basic questions like:

  • I need PHP code samples? - Immediately available on the code samples page.
  • What does the API cost? - Says that it is FREE on Getting Started and FAQ.
  • Can I save your data in my database? - Says it on the Usage Requirements
  • Do I have to show your logo? - Says it on the Usage Requirements

That is just the tip of the iceberg. I’ve posed this question before...are there enough doers in the world to make this whole API vision work? It’s hard to tell if its just my view, while in the pit of despair, or if it is just the way it is.

It seems like there will always be some users who need hand holding, and they refuse to read the self-service material available in the API area. When I’m hacking on an API, I always make sure I search exhaustively before I ask a question, but I’m discovering a new breed of developers who won’t search, won’t ask questions--then when you reach out to them they’ll ask for what they need, no matter how basic.

It seems, that self-service API resources are essential, but there will always be a segment of our audience who aren’t quite doers, they need more hand-holding and information presented to them before they get what they need.

See The Full Blog Post