{"API Evangelist"}

Using Anchors In Your FAQ And Other API Support Pages

I was going through some of the Twitter feeds of the APIs that I track on and noticed Spotify's team providing support to some of their API users with quick links / anchors to the answers in their API user guide available at developer.spotify.com. This might sound trivial, but having an arsenal of these links, so you can tweet out like Spotify does can be a real time saver.

This is pretty easy to do with a well-planned API portal and developer resources but is something you can rapidly add / change to using a frequently asked questions page for your API. The trick is to make sure you have anchors to the specific areas you are looking to reference when providing support for your community.

Another benefit of doing this beyond just developer support is in the name of marketing and evangelism. I'm often looking for specific concepts and topics to link to in my stories, and if an API doesn't have a dedicated page or an anchor for it, I won't link it--I do not want my readers to have to dig for anything. The trick here is you need to think like your consumers, and not just wear your provider's hat all the time.

When crafting your API portal, and supporting resources make sure you provide anchors for the most requested resources and other information related to API operations, and keep the links handy so you can use across all your support and marketing channels.

See The Full Blog Post


Is Your Sales Deal Size Just Too Big To Be Reading API Evangelist?

I am blessed to have people in the space who have supported what I do for the last six years. Companies like 3Scale, Restlet, WSO2, Cloud Elements, and others have consistently helped me make ends meet. Numerous individuals stepped up in May to help me make it through the summer--expecting nothing in return, except that I continue being the API Evangelist.

I do API Evangelist because I enjoy staying in tune with the fast-growing landscape of industries being touched by APIs. I believe in what is possible when individuals, companies, organizations, institutions, and government agencies embark on their API journey (aka digital transformation). I do not operate as the API Evangelist to sell you a product, service, or to get rich. Don't get me wrong, I do ok, but I definitely am not getting rich--all I got is the domain, Twitter account, and my stories.

The prioritization of sales and profits over what is really important in the space always blows my mind, but rarely ever surprises me. I find myself regularly worrying about the companies and individuals who focus on sales over actual transformation, but I have to admit my friend Holger Reinhardt's post about the motivations behind their Wicked (cool) open source API management made me chuckle. Their API management work was in response to a sales lead that "felt that our focus on ‘just enough API management’ was too narrow and not addressing the larger needs (and bigger deal) of the ‘Digital Transformation’ of the Haufe Group." << I LOVE IT!!!

I've been through hundreds of enterprise sales pitches, sitting on both sides of the table, and experiencing this bullshit song and dance over and over was one of the catalysts for leaving working with SAP in 2010 and starting API Evangelist. I just wanted to tell honest, real stories about the impact technology could make--not scam someone into signing a two or three-year contract, or be duped by a vendor into doing the same. Granted, not all sales people are scammers, but if you are in the business, you know what I'm talking about.

All I can say is I am very glad I do not have to live in a sales deal-driven world and I refuse to go back. To brag a little, I know that a significant portion of my readers are enterprise. People who work at IBM, SAP, Oracle, SalesForce, Microsoft, Capital One, and on, and on read my blog, and I want you all to know: That NONE of your deal sizes are too big, or too small to be reading my blog--I give a shit about all of you. However, maybe you could let me know what your expected budget might be? ;-)

See The Full Blog Post


I Am Digging Stripes New Interactive API Documentation Walkthrough

I am digging Stripes new documentation release, and specifically their interactive API documentation walkthrough. The new "try now" section of their documentation provides an evolve look at what is possible when it comes to providing your API consumers the documentation they need to get up and running.

The new documentation provides not just a code example of processing a credit card charge, they walk you through accepting a credit card, creating a new customer, charge the card, establish a recurring plan, and establishing a recurring customer subscription.

The walkthrough is simple, informative, and helpful. It helps you understand the concepts at play when integrating with the Stripe API, in a language agnostic way. I was super impressed with the ability to copy, paste, and run the curl commands at the command line, and when I came back to the browser--it had moved to the next step in the walkthrough. 

The new Stripe API documentation walkthrough is the most sophisticated movement forward in API documentation I've seen since Swagger UI. It isn't just documentation, in an interactive way--it walks you through each step, bordering on what I'd consider API curriculum. All without needing an actual live token--I wasn't even logged in. Additionally, Stripe made sure they Tweeted out the changes and included a slick GIF to demonstrate the new interactive capabilities of their documentation.

See The Full Blog Post


Going The Distance To Help API Consumers Find Their API Keys And Tokens

I am always amazed at how difficult it can be to obtain the API keys, or fire up an initial set of oAuth tokens when kicking the tires on a new API. I would also say that I am also regularly impressed the distance API providers will go to help API consumers obtain the keys they need to make a successful API call.

One example of this is present in the new Stripe API documentation. Their new code samples give you a slick little alert every time you see a demo key and mouse over. The alert gives you a quick link to log in and obtain the keys you need to make an actual call.

While I like this approach, I also  like the way Twitter does this and gives me a dropdown listing all of my applications, allowing me to choose from any of my current apps I have registered--maybe it is something that could be merged?

Both are great examples of API providers going the extra distance to make sure you understand how to authenticate with an API, and get your API keys and OAuth tokens. If you know of other good examples of how API providers are working to make sure authentication is as frictionless as possible, making API keys and oAuth tokens more accessible directly within API docs--let me know.

This is an area I think interactive documentation has made significantly easier, but things have seemed to stagnate in this area. It is definitely an area I'd like to see move forward, eventually providing cross-API provider solutions that developers can put to use.

See The Full Blog Post


Watching Out For Your API Keys & Tokens On Open Internet

I was just learning about Auth0's new password breach detection service, adding to the numerous reasons why you'd use their authentication service, instead of going at it on your own. It's an important concept I wanted to write about so that it was added to my research, and present in my thinking around API authentication and security going forward.

Keeping an eye out for important identity and authentication related information used as part of my API consumption is a lot of work--it is something that I'd love to see more platforms assist me with. I've written about AWS communicating with me around my API keys, and I could see an API key and token management solution be built on top of their AWS Key Management Service. I've also received emails from Github about my OAuth token that show up in a public repo (happened once ;-( ).

Many application developers do not have the discipline to always manage API keys & tokens in a safe and secure way (guilty). It seems like something that could become default for API providers--if you issue keys and tokens, then maybe you should be helping consumers keep an eye out for them on the open Internet << Which smells like an opportunity for some API-focused security startup. 

Have you seen any other API providers provide key and token monitoring services? Is there anything that you do as an API consumer to keep an eye out for your own keys and tokens? Search for them on Github via the API? Manually search on Google? I am curious to learn more about what people are doing to manage their API keys and tokens.

See The Full Blog Post


Providing A Dedicated Mobile SDK Page For Your API

Every API provider will have slightly different needs, but there are definitely some common patterns which providers should be considering as they are kicking off their API presence, or looking to expand an existing platform. While there are some dissenting opinions on this subject, many API providers provide a range of specific language, mobile, and platform SDKs for their developers to put to use when integrating with their platforms. 

A common approach I see from API providers when it comes to managing their SDKs is to break out their mobile SDKs into their own section, which the communications API platform Bandwidth has a good example of. Bandwidth provides iOS and Android SDKs and provides a mobile SDK quick start guide, to help developers get up and going. This approach provides their mobile developers a dedicated page to get at available SDKs, as well as other mobile-focused resources that will make integration as frictionless as possible.

Unless your anti-SDK, you should at least have a dedicated page for all your available SDK. I would also consider putting all of them on Github, where you will gain the network effect brought by managing your SDKs on the social coding platform. Then when it makes sense, also consider breaking out a dedicated mobile SDK page like Bandwidth--I will also work on a roundup of other providers who have similar pages, to help understand a wide variety of approaches when it comes to mobile SDK management.

See The Full Blog Post


More Considerations When Providing An Anonymous App For Your API Service

I wrote a post the other day about Postman.io having a limited, anonymous version of their API modeling tool. I stumbled across it while I was trying to upgrade my Stoplight.io account. Shortly after I tweeted out the blog post, John Sheehan (@johnsheehan) from Runscope chimed in with some wisdom on the subject.

Definitely, something to consider. In the current online environment, it might become quite a pain in the ass to maintain an anonymous app, as John points out. This is one reason I work to publish my API tooling as standalone JavaScript applications, which run 100% on Github. First off they run on Github infrastructure, and use Github's bandwidth. Second, this type of app is forkable, and people can choose to run them wherever they desire--on Github, or any other site they wish.

I'll keep an eye out for other anonymous apps built on top of API service providers, or individual APIs--maybe there are other successful models out there, or maybe there is also some other cautionary tales we should hear.

See The Full Blog Post


Managing The Apps Across All My API Accounts

I am going through all of my online accounts changing passwords, and one of the things I do along the way is check which applications have access to my digital self. Increasingly my accounts have two dimensions of applications: 1) apps I have created to allow me to make API calls for my system(s) 2) apps I have given access to any account using OAuth. This is a process that can take quite a bit of time, something that is only going to grow in coming years. 

The quickest example of this in the wild is Twitter. I have authorized 3rd party applications to access my account, and I have also developed my own applications, which have various types of access to my profile--this is how I automate my Tweets, profiling of the space, etc. I'm regularly deleting apps from both of these dimensions, which I tend to add as I test new services, and build prototypes. 

I really wish the platforms I depend on would allow me to manage my internal and 3rd party applications via an API. If I could aggregate applications across all the accounts I depend on, manage the details of these applications (including keys & tokens), and add and remove them as I need--that would be awesome! If nothing else, maybe this will put the bug in your ear to consider this for your own world, and you can help put the pressure on existing API providers to open up oAuth and app management APIs for us to help automate our operations.

See The Full Blog Post


Adding An Atom Feed For The API Evangelist Blog

The API Evangelist platform is far from perfect, there are always portions of it that just aren't finished yet (always work in progress). I am always thankful that people put up with my API Evangelist workbench, always changing and evolving. Even with this unfinished status, there are some unfinished or broken elements that are just unacceptable--one of these is the lack of an Atom feed for my blog.

Thankfully I have other folks in the space who are kind enough to remind me of what's broken when it comes to specifications, and ultimately what is broken on my website.

Thanks Erik for gently pushing back. In response I went ahead and added an Atom feed for the API Evangelist blog, to add to the existing RSS feed. I made sure the Atom feed validated and added a link relation to the header of the blog. I am going to do the same to all my individual research areas with the next push of their website template.

Syndication of my writing is important, so my blog is now available via RSS, Atom, and JSON. Thanks Erik for helping make sure the web is not entirely broken. ;-)

See The Full Blog Post


You Can Make Money While Also Doing Important Work For The API Space

I see a lot of companies doing things with APIs, and I often find myself struggling to find companies who are doing important things that benefit the community, have a coherent business model, and providing clear value via their services. In the drive to obtain VC funding, or after several rounds of funding, many companies seem to forget who they are, slowly stop doing anything important (ie. research, open source, etc.) with their platform, and seem to just focus on just making money. 

One phrase I hear a lot from folks in the space is, "it's just business", and that I should stop expecting altruistic behavior around APIs, and within the business sectors which they are impacting--APIs are about making money, and building businesses hippie! Often times I begin to fall for the gaslighting I experience from some in the API space, then I engage with services like CloudFlare.

I use CloudFlare for all my DNS, but I also stay in tune with their operations because of what they do to lead the DNS space, and because of their DNS API. I was going to craft this post after reading their blog post on the Cuban CDN, then I read their post on an evenly distributed future, and I'm renewed with hope that the web just might be ok--things might not be as dark as they feel sometimes.

I follow what CloudFlare is doing because their work represents the frontline of the API sector--DNS. This makes it not just about DNS, it also becomes about security, and potentially one of the most frightening layers of security--the distributed denial of service attack (DDoS). CloudFlare clearly get DNS, and care so much that they have become super passionate about understanding the web as it exists (as messy as it is), and pushing the conversation forward when it comes to DNS, performance, and security. 

CloudFlare makes DNS accessible for me, and for other less-technical professionals like my partner in crime Audrey Watters (@audreywatters), who also uses CloudFlare to manage her DNS, with no assistance from me. I operated my own DNS servers from 1998 until 2013, and it is something that I will never do again, as long as CloudFlare exists. CloudFlare knows their stuff and they help me keep the frontline of my domains healthy and secure.

There are a number of companies I look up to in the space, and CloudFlare is one of them. For me, they prove that you can build a real business, do important work that moves the web forward, be passionate about what you do, while also being transparent along the way. Knowing this is possible keeps me going forward with my own research, and optimistic that this experiment we call the web might actually survive.

See The Full Blog Post


If You Use API Definitions There Is No Excuse For Not Having An API Sandbox

I have long been a proponent of using API definitions, not just because you can deploy interactive API documentation, but because they open up almost every other stop along the API life cycle. Meaning, if you have an OpenAPI Spec definition for your API you can also generate SDKs using APIMATIC, and API monitors using Runscope. 

One of the examples I reference often is the API Sandbox solution appropriately named Sandbox. One of the reasons I use Sandbox in this way is that API mocking using API definitions is a pretty easy concept for developers to wrap their heads around, but also because their home page is pretty clear in articulating the opportunities opened up for your API when you have machine-readable definitions available.

Their opening text says it well, helping you understand that because you have API definitions you can "accelerate application development", and provide "quick and easy mock RESTful API and SOAP webservices". The presence of common API definition icons including API Blueprint, OpenAPI Spec, RAML, and WSDL then provide a visual re-enforcement for the concept.

Sandbox opens up mocking and sandbox capabilities, which I lump together under one umbrella which I call API virtualization. You can easily create, manage, and destroy sandboxes for your APIs using their API, and your API definitions. I envision API providers following Cisco's lead and having any number of different types of sandboxes running for developers to put to work, using server virtualization (virtualization on virtualization).

With the evolution of API definition-driven solutions like Sandbox for providing virtualized instances of your APIs, there really isn't any excuse for not having a sandbox for your API. For device focused APIs, a sandbox is essential, but even for web and mobile-focused APIs you should be providing places for your API consumers to play, and not requiring them to code against production environments by default.

See The Full Blog Post


CRX Extractor Wins For The Best Customer Quote Ever

Having quotes from your customers on your company website is a no-brainer. Finding the best examples of brands and companies putting your valuable service, or tool to work demonstrates it has value, and that people are using it.

While playing around with a new chrome add-on reverse engineering tool called CRX Extractor, I noticed the quote at the bottom of their page:

They win in my book for having a funny, but also pretty realistic endorsement for why you should be using a product. I'm using the tool to better understand how browser add-ons are putting APIs to work and evolve my own creations as well, but I can see reverse engineering them to make sure they are secure is a pretty important aspect of operating your company securely online.

When it comes to marketing your API, make sure you have quotes from smart people, as well as brands that people know, makes sense, but I would also add that making them funny, and allowing ourselves to laugh along the way can make a significant impact with the right people as well

See The Full Blog Post


An OpenAPI Spec For A Building Permits API

One of the reasons why crafting API definitions like OpenAPI Spec for our APIs, and openly sharing them on the web, is so that the pattern will get used, and reused by other API providers. That might sound scary to some companies, but really that is what you want--your API design used across an industry. Your API definition is not your IP, it is the magic behind your API, and the way you approach all the supporting elements around your API operations.

There are numerous industries where I'd like to see a common API definition emerge, and get reused, and one of the more obvious ones is in the area of building permits. Open Permit has shared their API definition, by publishing the OpenAPI Spec to drive their Swagger UI documentation. This is a great example of an API definition that should be emulated across the industry because the money to be made is not around the API design, but the portion of our economy that the API will fuel when it is in operation.

Can you imagine if all cities, contractors, and vendors who service the construction industry could put APIs to use, and even better, put common patterns to use? If you have ever tried to build something residential or commercial and had to pull a permit, you understand. This is one industry where APIs need to be unleashed, and we need to make sure we share all possible API definitions so that they can get used, and we aren't ever re-inventing the wheel.

See The Full Blog Post


A Wicked (Good) Open Source API Deployment And Management Stack

I was introduced to a new open source, Dockerized API operations solution called Wicked, that was developed by the integrated cloud and desktop solutions provider, the Haufe Group. There are a number of open source API management solutions out there, and an even greater number of API frameworks that can help you deploy your APIs, but Wicked is the first to span several areas of the API life cycle including DNSdeployment, containers, authentication, management, and documentation,

Built On Existing Open Source API Gateway
The Haufe Group built the core of Wicked on top of an existing open source API management solution, further augmenting, evolving, and improving on an existing solution:

Why reinvent the wheel? It makes sense to build on existing solutions for API management, developing on top of what is already being used by API architects and developers.

Simple Developer Onboarding
Wicked employs the latest approaches to allowing developers to onboard with an API, sticking to what is already working for API providers, and what developers expect: 

  • Authenticate with email and password - Let your users sign up with their email address and a password. Email addresses will be automatically validated by sending out verification emails.
  • Authentication with GitHub or Google - You may also configure signup and login using OAuth2 with GitHub and/or Google. These identities will be treated as 'verified' automatically.

I like that they let you use Github or Google on top of the standard email and password setup. I've been aggregating all my personal API developer accounts under my single @kinlane Github account, and when I set up a business account I authenticate using my @apievangelist Github account--more API providers should offer this, to help us all organize our accounts.

Using Modern API Authentication
There are a handful of proven approaches out there for allowing developers to authenticate against an API, and Wicked allows for two of the most common approaches:

  • API Key or OAuth 2 - Out of the box, wicked enables fast securing of your API using API Key authentication or OAuth 2 Client Credentials Flow.

Allowing for either API key or OAuth will cover 75% of the use cases companies are looking for when securing their digital resources. Most public resources will just need an API key which acts as the identifier, but for personally identifiable information, OAuth is essential.

Enabling API Service Composition
Every successful API provider knows that you don't provide the same access for all developers, and service composition is an essential way to approach this--Wicked provides the essentials in this area: 

  • Implement Rate Limiting - Using Mashape Kong's rich functionality, implement rate limiting for your APIs, wherever needed.
  • Subscription Plans - API definitions can be associated with subscription plans, which can carry additional settings, e.g. different rate limits for different users.
  • Group based rights to APIs - Define custom user groups and assign those groups to users in order to limit access to specific APIs to specific groups. The Admin group can also be assigned.
  • Group based rights to custom content - The content section also supports group-based access, e.g. to How-tos or tutorials.
  • Subscription Approval Workflow - API Plans can be configured to require an approval of subscription; you will be sent an email to a predefined email address to the approval request.

While I am not a big fan of API approval workflows, as I prefer resources to be self-service, I was intrigued by the email approval feature, allowing for a (hopefully) frictionless onboarding flow that can add an additional layer of security for our most valuable of API resources.

Providing The Necessary Application Mangement
APIs are all about developing applications, and Wicked allows for the identification of apps, and the incorporation of these apps into the service composition workflow: 

  • Application Concept - In order to subscribe to an API, a user needs to create an application (which is the client of the API); APIs are coupled with applications, not users.
  • Application Owner Roles - Applications can be shared among users, using different roles on the application: Admin/Owner, Collaborator, and Reader.

Users may have one or many apps which integrate with one or many APIs. This many to many relationships provide a robust way to manage API consumers, and potentially the multiple applications which they will develop.

Interactive API Documentation
No API in 2016 is complete unless it has interactive documentation, and Wicked sticks with what works in this area and provides documentation for APIs using Swagger UI and OpenAPI Spec

  • Swagger UI Integration - In order to view the APIs in more detail, wicked has integrated Swagger UI, with configurable direct access to the backend services.

Using open API definitions like OpenAPI Spec, as well as providing up-to-date interactive API documentation is pretty much much the new baseline for APIs these days, and Wicked keeps up.

Scalable Deployment
Next, as if that wasn't enough, you get te scalable deployment of APIs using Docker. Wicked weaves together the DNS, deployment, and management of your APIs, and allows for modular deploy with Docker, and scaling with Docker Compose:

  • Docker Deployment - The entire APIm solution is deployed using docker; everything runs in docker, enabling deployments to whatever infrastructure supports it.
  • Scaling With Docker Compose - By using docker-compose, the deployment of your API Management solution can be easily scaled to use multiple instances of Kong, behind a powerful HAproxy.

This type of API deployment is how all APIs will be deployed in the future. We have a lot of work ahead of us when it comes to decoupling our legacy infrastructure, but Wicked gives us the tools we need to get this done--providing a fuller open source stack which we can more confidently bake into our infrastructure.

There are two things that stand out for me about Wicked. 1) It spans deployment and management in a scalable way 2) It is built using the best of breed open source tooling, specifications, and standards available out there right now--Kong, HAproxy, OpenAPI Spec, Swagger UI, and Docker.

I'm just getting going with Wicked. It makes me happy to see API operations solutions like this come together. I'm just getting going reviewing the stack, and I am really liking the motivations behind why they did it, and how they are doing it--more to come.

See The Full Blog Post


Who Is Going To Do The DevOps Aggregation API Platform?

There are two distinct types of APIs I keep an eye on. One is what I call my life cycle APIs, which are the APIs of the service providers who are selling services and tools to API providers and developers. The second category is what I call my stack network, and these are the individual API providers, who offer a wide range of API resources--you can find both of these types on the home page of API Evangelist

The 50+ life cycle APIs I track on can be used by companies to manage almost every stop along a modern API life cycle. In theory, all of these service providers have APIs. In reality, they do, but they do not practice what they preach and often do not make their APIs easily discoverable. I have said it a thousand times before--if you sell online services to API providers, you should have an API. Period.

At some point in the future, I will have profiled all of the companies included in my API life cycle research, like I did for API monitoring, and be able to provide a comprehensive API stack across all the providers for all stops along the life cycle. Ideally, each provider would have their own OpenAPI spec, but I'm still getting many of them to make their APIs public, convincing them of the importance of also having an API definition for their API will come next. Then I'll continue pushing on them to allow for the import / export of API definitions, so their customers can more easily get up and running with their services--if you need an example of this in the wild, take a look at Sandbox, or over at API Metrics.

I'd love to see someone take this idea and run with it beyond what I'm able to do as a one-man act. There are numerous API aggregation solutions already out there for financial, healthcare, images, documents, and more. What about an aggregated API across providers in the name of DevOps or microservices orchestration? An aggregated solution would allow you to automate defining of your APIs in multiple formats with API Transformer, deploy them using Docker or Heroku APIs, manage with 3Scale APIs, deploy sandboxes with Sandbox, monitor with Runscope, and almost every other stop along the life cycle. 

I'm sure I've written this one up before, but I couldn't find it, so I wanted to get a fresh post up on the subject. With all the agile, orchestration, DevOps, microservices, continuous integration goingz on, having a coherent, cross-vendor API stack, and a suite of the usual analytics, billing, and other vital middleware services just makes sense. Let me know when you get up and running, and I'll send over my bank account information for the royalty payments. ;-)

See The Full Blog Post


The Expanding API Layers That Overlap Our Physical And Virtual Worlds

I wrote the other day about the interesting opportunity opening up within the satellite imagery API layer, and earlier about the similar opportunity that is being expanded within the fast growing dimension of our world being opened up with drones. Layers within maps are nothing new, and is something that Google has pushed forward early on in the history of APIs with Google Maps, but I feel is further being expanding on as APIs open new dimensions like satellites and drones. Then being further expanded on by adding API access to each layer for augmenting, and injecting other valuable API resources into these newly created API dimensions.

Let's see if I can successful describe the multiple API dimensions being opened up here. APIs are providing access to maps of our physical world, whether it is on the ground, from the air with drones, or from space with satellites, and these API-driven maps have layers, which are also made available via APIs, allowing other API driven resources like weather, forest fires, restricted spaces, and temporary or permanent elements are being injected. Once injected, these API-driven mapping resources with API injected resources are also being made available via APIs, providing entirely new, and specialized resources--that is a lot of APIs!

I am not even touching on the physical devices who put these maps to work also possessing APIs, like the drones, GPS units, cars, etc. This is just the expanding layer that is opening up via the multitude of API driven mapping resources and is further expanded when you look at the video layer which drones, mobile phones, automobiles, security cameras, and other Internet-connected devices are opening up. Drones, automobiles, and others will share layers with the mapping resources, but other video resources also will possess their own layers for augmenting the experience on the web, mobile, and television.

The part of this that is really striking to me isn't just the overlapping layers between mapping, video, and other channels, it is the overlap between our physical and virtual worlds. Think what Pokemon Go has done for gaming, but now consider drones, consumer automobiles, as well as commercial fleets. It can be very difficult to wrap your mind around the different dimensions of opportunities opening up, but it doesn't take much imagination to understand that there is a growing opportunity for APIs to thrive in this expanding universe.

See The Full Blog Post


Sharing Your API Platform Road Map And Telling The Story Like Readme.io

Sharing your platform's road map with the public, and your community is an often overlooked aspect of API operations but is one that can go a long way to communicate your plans for the future with your community. This is why I carved the concept out into its own research area, to help me better understand how the successful API providers, as well as API service providers are publishing, sharing, and communicating around their road map.

One example of this recently is out of the API documentation service provider Readme.io, who didn't just publish a nice, simple, and clean road map for their platform, they also told the story of the process. This is a great way to announce that you have a road map for the platform but is also something you should repeat as often as possible, telling the story of what you just added to the road map and as much detail on why.

Sharing your road map, and the story behind goes a long way in lowering the anxiety around what the future holds for your API consumers, something that lets them know that you care about them enough to share what you have planned. In my opinion, a road map for an API platform shows that you have empathy for your community, and is something I like to encourage and support, by showcasing the process of your road map storytelling here on my blog when I can.

See The Full Blog Post


Prioritizing Commonly Requested Information With Your API Deployment

I was reading the post from open data service provider Socrata about "putting citizens first" when it comes to opening up city, county, state, and federal government data. One of the headlines they showcased was "Texas overhauls open data portal, prioritizes commonly requested info"--which is a pretty sensible thing to consider for not just government, but also companies thinking about what to open next.

First, let me emphasize that I am talking about open data that is already published on the web in another format (or should be). What the State of Texas is doing is what I call the low-hanging fruit for API deployment--if it is on your website, it should also be available in a machine-readable format. Ideally, you offer HTML, as well as JSON, XML, and other relevant formats side by side within a single domain using content negotiation, but no matter how you accomplish it, the priority is making sure that commonly requested information is accessible to those who need it.

It is a shame that Texas is only now considering this with the latest revision of their portal, ideally government agencies and companies would be applying this way of thinking by default. If it is on your website as HTML, most likely it has already been deemed important, which is why it was made self-service on the open web in the first place. If you are planning on deploying an API or open data portal, and you are just wondering where you should start, make sure to learn from the State of Texas, and prioritize the commonly requested information.

See The Full Blog Post


API Providers Could Add A Page To Showcase Their Bots

I am coming across more API providers who have carved off specific "skills" derived from their API, and offering up as part of the latest push to acquire new users on Slack or Facebook. Services like Github, Heroku, and Runscope that API providers and developers are putting to work increasingly have bots they employ, extending their API driven solutions to Slack and Facebook.

Alongside having an application gallery, and having an iPaaS solution showcase, maybe it's time to start having a dedicated page to showcase the bot solutions that are built on your API. Of course, these would start with your own bot solutions, but like application galleries, you could have bots that were built within your community as well.

I'm not going to add a dedicated bot showcase page until I've seen at least a handful in the wild, but I like documenting these things as I think of them. It gives me some dates to better understand at which point did certain things in the API universe begin expanding (or not). Also if you are doing a lot of bot development around your API, or maybe your community is, it might be the little nudge you need to be one of the first APIs out there with a dedicated bot showcase page.

See The Full Blog Post


What Is A RESTful API And Why Does It Matter To IoT?

I'm pretty skeptical about many of the reasons behind why companies are connecting devices to the Internet using APIs--I am just not convinced this is the best idea when we already have so many security issues with the standard, and mobile web. Regardless, I'm constantly working to understand the motivation behind a company's motivation to do APIs, as well as what they are telling their customers. 

I published a story last week about defining the industrial programmable automation controller (PAC) strategy using an API, which focuses on the approach by Opto 22. To support their efforts the industrial automation provider offers up a dedicated page to educating their customers on why you would want to use REST, providing some bullets:

  • Archive I/O and variable data from the PAC directly into Microsoft SQL Server using Microsoft's T-SQL—no OPC or ODBC required
  • Read data from and write data to the PAC from your browser or web-based application using JavaScript.
  • Read or write PAC data using your favorite programming languageC, C++, C#, Java, PHP, Python, and many more
  • Build a mobile application that directly accesses data on your PAC—using Java, Swift, or Xcode 
  • Build a data flow application for communicating with cloud platforms and cloud APIs, using Node-RED and our new SNAP PAC Nodes.

Each of the industrial controllers "includes an HTTP/HTTPS server and RESTful API, compatible with any programming language that supports JavaScript Object Notation (JSON)". In my opinion, this reflects the wider API space that is serving the web and mobile objectives, allowing for integration using any programming language, as well as opening up the devices to API orchestration solutions using iPaaS, and the variety of other API service provider solutions available in the market.

Ultimately I think using web technology is inexpensive, and avoids the usage of proprietary, vendor specific solutions. As the ability to offer up a web server on any physical object becomes easier and cheaper, the usage of web APIs to interact, integrate, and orchestrate around physical objects will only increase, for better or worse.

See The Full Blog Post