{"API Evangelist"}

A Unique and Personal API Onboarding Experience

I have written many times before about the right way to onboard with an API, as well as how not to onboard with an API. I see a lot of APIs, and can tell you which APIs have put thought into the process, and those who haven't. Helping companies smooth out the sharp edges on their API onboarding is something I spend a lot of time doing, so I work hard to make sure the topic shows up regularly in my writing.

Today I want to highlight a slight different onboarding email I received from Weather2020:

Hi there Mr. Lane!

First off I'll get my lil bit of gushing out of the way.  I really enjoy what you're doing out there in the world.  I love your commitment and passion to the growing world and need for APIs and your focus on the narrative vs. straight technical details.  So even if you find some reason to hate what we have going on here just please keep up the great work.

But now without further delay, I generated a key that grants you an unlimited number of calls.  That key is: c47c5e6e52ae4ae9183e65f30390693f3ee

The structure of our API calls are:http://api.weather2020.com/[APIKEY]/[LAT],[LNG]

So a sample functioning call for us here in Kansas City is:http://api.weather2020.com/c47c5e6e52ae4ae9183e65f30390693f3ee/39.099727,-94.578567


Just because you're obviously just a bit of an enthusiast I'll let you know I have 2 other call structures that deliver the forecast data based on zip codes and city names.  I use them strictly for our internal purposes but I've enabled your API key to work with them as well.  Just in case you want to play around with them.  They're not that super impressive but involved a very different kind of internal data mapping so I'm mildly proud of em.http://api.weather2020.com/zip/c47c5e6e52ae4ae9183e65f30390693f3ee/90210http://api.weather2020.com/city/c47c5e6e52ae4ae9183e65f30390693f3ee/Portland,OR


I plan to have some documentation at the root API domain very soon ( ie. here: http://api.weather2020.com ) .  So hopefully none of the returned data is too much of a mystery.  If you have any questions just let me know.  Also if you have any feedback whatsoever I'd love to hear it.  I can always use some wisdom!


Enjoy!

I do not always read the API signup emails I receive, but I do store them in a folder for later review, and I happen to read this one today. It always makes me happy to receive nice emails from my readers, but the fact that this was also in the form of an API onboarding response--made me smile.

I added a couple random characters to the API key above, so don't worry about the security side of this post. I don't expect everyone to personalize their new developers message like this, but I do think it is helpful to let developers know there is a human behind the self-service registration for any API--it could go a long way.



Usage Of Swagger For The APIs At The UC Santa Barbara Lab for Research on Adaptive Computing Environments

This is a Github issue submission I received, in response to whether or not anyone is doing anything interesting with Swagger. In the lead up to talks about Swagger next week at Gluecon, in Colorado. I'm pretty impressed with this work at UCSB, and while I am processing it, I wanted to share with you, and hopefully stimulate others to share what they are working on behind the scenes, using Swagger--I've gotten some pretty cool submissions so far.

We use Swagger in a series of on going research projects at the RACELab of UC Santa Barbara. Our research focuses on designing and implementing new mechanisms for governing APIs in cloud platforms. Following are some of our published works that make use of Swagger.

In first two papers, we use Swagger as a mechanism for describing the syntax and semantics of web APIs. The base Swagger standard covers all the crucial syntactic features of the APIs. We extended the base Swagger specification to include some simple axiomatic semantics (API preconditions and postconditions). We use this syntactic and semantic information to measure the similarity between different API alternatives.

In EAGER (Enforced API Governance Engine for REST), we use the base Swagger 1.1 standard to describe all APIs deployed into the cloud. We auto-generate Swagger descriptions from Java (JAXRS) source code at the compile-time using a custom Maven plug-in. Once uploaded to the cloud, we use Swagger descriptions to validate APIs, enforce policies on them and establish the backward compatibility between different versions of the same API. This way we can prevent or warn the API developer when a backward incompatible API change is being rolled out into a production cloud.



Are You Doing Anything Interesting With @APIBlueprint? Or Know Someone Who Is?

I am preparing for a big week of discussion around API definitions at Gluecon, and in addition to working on my Swagger research, I kicked off deeper research into API Blueprin, looking for the companies that are doing interesting things in the space, using the machine readable API definition format.

As i do with all my work, I have a Github repository setup for the research, allowing me to publish all of my work publicly, and manage feedback and engagement with the community, using my Github workflow. If you want to make any changes to the data you can fork and submit a pull request, or you can also suggest companies I should be looking at, as a Github issue.

So far, I've broken things into four areas:

  • Platform Integrations - Companies who are using the API Blueprint specification as part of their platforms--essentially baking it in.
  • External Integrations - Companies and individuals who have integrated API Blueprint into an existing platform, or framework, from the oustide-in.
  • Apiary - API providers who are using Apiary as part of their API operations, providing interactive documentation to their consumers.
  • Building Blocks - Some of the common patterns I'm tracking on, regarding how API Blueprint is being applied. 
  • Tooling - What toolin ghas emerged that puts API Blueprint to work, from documentation, to generating code samples, to IDE integration.

I'm working on organizing the tooling that I have found so far, but I figured I'd publish what I have currently, and ask for suggestions about anything that is missing. If you know of a platform that is using API Blueprint, either baked directly in, via an external framework, or are just using Apiary for its documentation, and management platform -- please let me know, by submitting a Github issue.

I know there is a lot more API Blueprint out there, and if you are doing something cool with the API Blueprint specification, there is a good opportunity for it to be included in the discussion next week. If you don't share your story, nobody will know, and there are a huge amount of fence sitters right now when it comes to API definitions--people just waiting, and watching for the right sign to jump in.

I'm going to be writing a lot about API definition formats this week, priming my brain for the conversation at Gluecon next week in Colorado. I apologize in advance. ;-) And thanks for sharing your stories!



It Will Be A Busy Week For API Industry Next Week At Gluecon

I am preparing to head to Colorado next week for Gluecon--one of my can't miss events in the API space. Gluecon is always a great place to be, to discuss the API space with the folks who are leading the charge, but this year is shaping up to be a particularly important one. There are number of things happening this year, primarily focused around API definitions, that stand to have a pretty significant impact on how the space operates.

To help showcase the goings on next week, I wanted to walk through my schedule, which I think speaks for itself. Starting next Tuesday, May 19th, we have two events:

Then on the afternoon of Wednesday May 20th, I am moderating the API session track on the main stage:

  • 1:30-1:45 - Track introduction, Kin Lane (@kinlane)
  • 1:45-2:15 - API Readiness: Visualizing and Virtualizing -- Lorinda Brandon (@lindybrandon), SmartBear
  • 2:15-2:45 - How REST APIs Can Glue All Types of Devices Together -- Jerome Louvel, (@jlouvel) Restlet
  • 2:45-3:15 - Roll-your-own API management platform with nginx and Lua -- Jon Moore(@jon_moore), Comcast
  • 3:15-3:30 - Discussion (with audience) led by Kin Lane (@kinlane)
  • 3:45-4:15 - Building a Node.js API with Swagger -- Jeremy Whitlock (@whitlockjc)
  • 4:15-4:45 - Architectural Patterns for Scaling Microservices and APIs -- Lori MacVittie (@lmacvittie), F5 Networks
  • 4:45-5:00 - Track conclusion by Kin Lane (@kinlane)

Then after the session I am doing a keynote on the main stage on the Tech, Business, and Politics of APIs in 2015, where I'll conclude the latest talk I've been doing around where I see the space going, rooted in stories out of the evolution of my own infrastructure. I first gave the talk at 3Scale in Barcelona, continued to evolve for the audience at APIDays Mediterranea, and will conclude with a version of it at Gluecon.

Many of the core people who are working on the Swagger definition will be present at Gluecon, and while much of the conversation will also be about the wider API space, and other API definition formats, there will be some important discussion about the future of Swagger, and what is next for the open API definition format. In addition to the in-person discussion throughout the week, there will be an virtual gathering of the Swagger working group at the end of the week as well.

Another part of the discussion next week will also be around the API definition format APIs.json, which since we launched the format last year at Gluecon, it make sense to talk about next steps, and some significant additions to the platform that has occurred in recent weeks. APIs.json, bundled with the potential of leading formats like API Blueprint, and Swagger, are delivering a growing number of services, and tooling to almost every step of the API lifecycle in 2015--Gluecon is where we get together to discuss.

If your are applying API definitions to your API lifecycle currently, I strongly urge you to get to Colorado next week for the discussions. I know it is a week away, but getting to Colorado is pretty easy, and this is a conversation you will not want to miss. As usual Gluecon is proving to be where some of the most important conversations occur, in the halls of the Omni Interlocken, and on the stools in the Taproom--we will see you there.



Are You Doing Anything Interesting With Swagger? Or Know Someone Who Is?

I am preparing for a big week of discussion around Swagger next week, and I'm spending time going through Swagger research project, refreshing some of the companies I know are doing interesting things in the space, using the machine readable API definition format, Swagger.

As i do with all my work, I have a Github repository setup for the research, allowing me to publish all of my work publicly, and manage feedback and engagement with the community, using the Github workflow. If you want to make any changes to the data you can fork and submit a pull request, or you can also suggest companies I should be looking at, as a Github issue.

So far, I've broken things into four areas:

  • Platform Integrations - Companies who are using the Swagger specification as part of their platforms--essentially baking it in.
  • External Integrations - Companies and individuals who have integrated Swagger into an existing platform, or framework, from the oustide-in.
  • Swagger UI - API providers who are using Swagger UI as part of their API operations, providing interactive documentation to their consumers.
  • Building Blocks - Some of the common patterns I'm tracking on, regarding how Swagger is being applied. 

I'm working on organizing the tooling I have found so far, but I figured I'd publish what I have currently, and ask for suggestions about anything that is missing. If you know of a platform that is using Swagger, either baked directly in, via an external framework, or are just using Swagger UI for its documentation -- please let me know, by submitting a Github issue.

I know there is a lot more out there, and if you are doing something cool with the Swagger specification, there is a good opportunity for it to be included in the discussion next week. If you don't share your story, nobody will know, and there are a huge amount of fence sitters right now when it comes to Swagger--people just waiting, and watching for the right sign to jump in.

I'm going to be writing a lot about API definition formats this week, priming my brain for the conversation at Gluecon next week in Colorado. I apologize in advance. ;-)