17 Nov 2014
I was reviewing an API over the last couple of weeks--I signed up for an account, came back several times, and made a handful of API calls in hopes of learning more about how the API works. This is something I do a lot, and it is always interesting to experience the on boarding process (or lack of) for APIs.
I first signed up about two weeks ago for this particular API, and within 48 hours I received an email asking if I needed help with my integration--that was nice of them. I like getting an email from the provider, and the more human it is, the better. At this point I didn't need any help, I’m just playing, learning, and depending on the self-service resources made available to me via the API ecosystem.
About a week later I get another email, again asking if I need help. At this point I’ve put down the API, but when I pick back up I might respond to the platform then, but I just have more learning to do before I have questions. Then about a week later, right before I was about to pick up the API again, I got another email asking me what my plans were, putting more pressure on me to share my plans for how I was going to be using an API, which I'm just not sure yet.
I am not your usual API consumer. I know this. However this API, I was actually planning on integrating into my core API tracking system at some point, so in addition to being the API Evangelist who might write a story, there is a good chance I will become a customer. I really like, and believe in the self-service nature of APIs, and while I like getting an email letting me know someone is home, I tend to be turned off by each consecutive email--nothing reminds you are in someones sales funnel, like a series of emails.
When you consider the touch points for your API on-boarding flow, make sure and think about the different types of users who will be registering, and the fact that not everyone will fit squarely in your perfect funnel definition. You want to make sure your API consumers know that someone home, and that you are there to help, but you really should rely on your self-service resources to get the bigger job done. Your initial email after I sign up should do this, then leave the next steps up to me, and be very thoughtful, and possibly dynamic with each engagement after that.
12 Nov 2014
When I landed on the version 3.0 landing page for the Mailjet API, the first thing I noticed was their API configuration API. Providing a set of API endpoints for managing my own API usage is definitely something I can get behind, and think it is something worth showcasing.
As part of the API Configuration portion of their email API, Mailjet provides five separate endpoints for users to manage their API developer account.
- /apikey - Manage your Mailjet API Keys. API keys are used as credentials to access the API and SMTP server
- /apikeyaccess - Access rights description on API keys for subaccounts/users.
- /apikeytotal - Global counts for an API Key, since its creation
- /apitoken - Access token for API, used to give access to an API Key in conjunction with our IFrame API
- /metadata - Mailjet API metadata
I like this approach to providing developers with API access to their developer account details. It is an approach I’d like to explore and standardize using the 3Scale API. I think it is something I've written about before, but I couldn't find it.
API access to a developer account is something I haven't seen anywhere else, but I'll definitely be using Mailjet as a blueprint for demonstrating what is possible, and see if I can’t convince other API providers that it is a feature they should consider.
10 Nov 2014
As the Oracle v Google API copyright case was on its way to the Federal Circuit Court in 2012, the EFF reached out to me for help in crafting stories of how important it is that APIs remain free of copyright, ensuring they remain open and interoperable. I shared three stories, one on cloud computing and AWS APIs, the second on Delicious APIs, and the third on Instagram APIs, all reflecting three different scenarios that would never have happened if APIs were copyrightable.
A couple weeks ago EFF reached out again, asking for my signature again, on another Amicus Brief to support Google’s request of the Supreme Court to review the circuit courts decision, and reverse it. As it stands right now, there is a precedent that copyright can be applied to APIs, and even though the case itself is moving onto the question of fair use, if we let the current decision stand, other companies can follow Oracle’s damaging lead and sue for protection of their APIs--which is why we need to convince the Supreme Court to review, and overturn the very damaging decision.
We expect that the Supreme Court will decide whether or not to grant Google’s petition to review the Federal Circuit’s decision sometime in January or February of 2015. So I need your help to stir up buzz around the issue, and post stories on your blog, call your congressman, and light up any other channel you can, to help educate people about the importance of the issue. When the Supreme Court takes on the case (which I feel strongly they will), we will need to regroup, and refile, a more expansive brief on the importance of APIs remaining free of copyright.
I’m working to expand my restaurant menu analogy, to help people understand the importance of APIs, but if you have other analogies that you think would help the Supreme Court understand the separation of API interfaces, and their supporting server side or client side code, please share with me so I can work with the EFF to potentially include in the next brief that is filed. APIs are touching every sector of business in 2014, and if we allow Oracle’s copyright claim to stand, we are in danger of pouring glue into the gears of each of these business sectors, at a point in time where we need to introduce as much lubrication, and transparency as we possible can, to ensure that the web, mobile, and Internet of Things applications built on APIs remain open and interoperable--ensuring they serve not just their platform owners, but also developers, and end-users equally.
Join me, in helping bring awareness to the issue, which right along with Net Neutrality, is one of the most important issues we currently face when it comes to deciding the future of technology, and how our society works, shares, collaborates and interoperates in this new online digital world we have created for our world.
10 Nov 2014
You can find me in San Francisco tomorrow, at the Kabuki Hotel for SF MusicTech. I'm moderating a panel, dubbed “API Ecosystem”, where I will be talking APis with Antti Silventoinen (@Lamantiini) of Music Kickup, Justin Woo (@jzwoo) of PayPal / Braintree, Steven Willmott (@njyx) of 3Scale, and Bill Hajjar from Senzari.
I'm planning on walking the panelists through the world of API design, development, management, and focus on API monetization, but I suspect that we'll keep things pretty relevant to the experience, and diversity we will have present on stage. There is a healthy mix of music industry focused providers like Music Kickup, and Senzari (aka Music Graph), but also API architecture provider 3Scale, and payment API pioneer Paypal / payment API startup Braintree.
You can catch the panel tomorrow at 2PM, in the spring room. Let me know if there is anything you'd like me to discuss with Antti, Justing, Steven, and Bill, during the panel. I’ll be hanging out at SF Music Tech all day, and of course drinking beers in SF tomorrow evening--let me know if you want get together and talk APIs!
10 Nov 2014
I've been crafting Swagger 2.0 definitions for many of the leading APIs i track on lately, and to help alleviate my pain and suffering, I’m willing to write about your company if you write your own Swagger 2.0 spec. I’m sorry, this is really important work, but it can be very grueling detail work, and I'd really like your help!
If you send me a 80% complete Swagger 2.0 specification, or for that matter, an API Blueprint or RAML specification, I will review your API efforts on the API Evangelist blog. I'm pretty adamant that all APIs today should have a machine readable definition in a popular format like Swagger or API Blueprint, as well as each API developer program possessing an APIs.json index of all of their APIs, including a reference to the machine readable API definition.
I’m determined to hand craft machine readable Swagger specs for the best APIs out there, and in time I will do this, but I could really use the help of API providers as well. Send me a link to your Swagger spec, and I’ll make sure a story gets into my story queue. I would add a disclaimer, that you need to make sure your API offers value, and your overall effort is thoughtful, otherwise I may call you out on some things. :-)
Once we get to a point where all APIs have a machine readable definition, we will start seeing entirely new opportunities around API design, deployment, management, integration, and discovery. I'm determined to bootstrap the work that will help us get to this point, but damn, I sure need some help. Tweet at me, or feel free to email me a link to any machine readable API definitions that you know of. #thanks