These are the news items I've curated in my monitoring of the API space that have some relevance to the API definition conversation and I wanted to include in my research. I'm using all of these links to better understand how the space is testing their APIs, going beyond just monitoring and understand the details of each request and response.05 Apr 2018
I’m always looking out for examples of API providers who have invested energy into formalizing process around the business and politics of API operations. I’m hoping to aggregate a variety of approaches that I can aggregate into a single blueprint that I can use in my API storytelling and consulting. The more I can help API providers standardize what they do, the better off the API sector will be, so I’m always investing in the work that API providers should be doing, but doesn’t always get prioritized.
The other day while profiling the way that Nest uses Server-Sent Events (SSE) to stream activity via thermostats, cameras, and the other devices they provide, and I stumbled across their branding policies. It provides a pretty nice set of guidance for Nest developers in respect to the platform’s brand, and something you don’t see with many other API providers. I always say that branding is the biggest concern for new API providers, but also the one that is almost never addressed by API providers who are in operation–which doesn’t make a whole lot of sense to me. If I had a major corporate brand, I’d work to protect it, and help developers understand what is important.
The Nest marketing program is intended to qualify applications, and then allow them to use the “Works with Nest” branding in your marketing and social media. To get approved you have submit your product or service for review. As part of the review process verifies that you are in compliance with all of their branding policies, including:
To apply for the program you have to email them with all the following details regarding the marketing efforts our your product or service where you will be using the “Works with Nest” branding:
- Description of your marketing program
- Description of your intended audience
- Planned communication (list all that apply): Print, Radio, TV, Digital Advertising, OOH, Event, Email, Website, Blog Post, Email, Social Post, Online Video, PR, Sales, Packaging, Spec Sheet, Direct Mail, App Store Submission, or other (please specify)
- High resolution assets for the planned communication (please provide URL for file download); images should be at least 1000px wide
- Planned geography (list all that apply): Global, US, Canada, UK, or other (please specify)
- Estimated reach: 1k - 50k, 50k- 100k, 100k - 500k, or 500k+
- Contact Information: First name, last name, email, company, product name, and phone number
Once submitted, Nest says they’ll provide feedback or approval of your request within 5 business days, and if all is well, they’ll approve your marketing plan for that Works with Nest product. If they find any submission is not in compliance with their branding policies, they’ll ask you to make corrections to your marketing, so you can submit again. I don’t have too many examples of marketing and branding submission process as part of my API branding research. I have the user interface guide, and trademark policy as building blocks, but the user experience guide, and the details of the submission process are all new entries to my research.
I feel like API providers should be able to defend the use of their brand. I do not feel API providers can penalize and cut-off API consumers access unless there are clear guidelines and expectations presented regarding what is healthy, and unhealthy behavior. If you are concerned about how your API consumers reflect your brand, then take the time to put together a program like Nest has. You can look at my wider API branding research if you need other examples, or I’m happy to dive into the subject more as part of a consulting arrangement, and help craft an API branding strategy for you. Just let me know.
Disclosure: I do not “Work with Nest” – I am just showcasing the process. ;-)
I recently watched a BBC documentary about the history of the branding used as part of the London Underground. I’m pretty absorbed lately with using public transit as an analogy for complex API implementations, and moving beyond just using subway maps, I thought the branding strategy for the London Underground provided other important lessons for API providers. The BBC documentary went into great detail regarding how much work was put into standardizing the font, branding, and presentation of information for each London Underground, to help reduce confusion, and help riders get where they needed, and making the city operate more efficiently.
As I continue to study the world of API documentation, I think we have so much work ahead of us when it comes to standardizing how we present our API portals. Right now every API portal is different, even often times with multiple portals from the same company–see Amazon Web Services for example. I think we underestimate the damage this has to the overall API experience for consumers, and why we see API documentation like Swagger UI, Slate, and Read the Docs have such an impact. However this is just documentation, and we need this to occur as part of the wider API portal user experience. I’ve seen some standardized open source API portal solutions, and there are a handful of API portal services out there, but there really is no standard for how we deliver, brand, and operate the wider API experience.
I have my minimum viable API portal definition, and have been tracking on the common building blocks of API operations for eight years now, but there are no “plug and play” solutions that users can implement, following any single approach. I have the data, and I even have a simple Twitter Bootstrap version of my definition (something I’m upgrading ASAP), but in my experience people get very, very, very hung up on the visual aspects of this conversation, want different visual elements, and quickly get lost on the functional details. I’m working with my partners APIMATIC to help standardize their portal offering, but honestly it is something that needs to be wider than just me, and any single provider. It is something that needs to emerge as a common API portal standard. If we can bring this into focus, I think we will see API adoption significantly increase, reducing much of the confusion we all face getting up and running with any new API.
I spend a lot of time monitoring API platforms, thinking about different ways of identifying which ones are taking control of the conversation around how their platforms operate. One example of this out in the wild can be found when it comes to bots, by doing a quick look at which of the major bot platforms own the conversation around this automation going on via their platforms.
First you take a look at Twitter, by doing a quick Google search for Twitter Bots:
Then you take a look at Facebook, by doing a quick Google search for Facebook Bots:
Finally take a look at Slack, by doing a quick Google search for Slack Bots:
It is pretty clear who owns the conversation when it comes to bots on their platform. While Twitter and Facebook both have information and guidance about doing bots they do not own the conversation like Slack does. Something that is reflected in the search engine placement. It is also something that sets the tone of the conversation that is going on within the community, and defines the types of bots that will emerge on the platform.
As I’ve said before, if you have a web or mobile property online today, you need to be owning the conversation around your API or someone eventually will own it for you. The same comes to automation around your platform, and the introduction of bots, and automated users, traffic, advertising, and other aspects of doing business online today. Honestly, I wouldn’t want to be in the business of running a platform these days. It is why I work so hard to dominate and own my own presence, just so that I can beat back what is said about me, and own the conversation on at least Google, Twitter, LinkedIn, Facebook, and Github.
Seems like to me, if you are going to enable automation on your platform via APIs, it should be something that you own completely, and make sure you provide some pretty strong guidance and direction.
API branding is an area that I find to be contradictory in the space, with the loss of brand control being in the top concerns for companies when doing APIs, while simultaneously one of the most deficient areas of API operations, with most API providers have no branding guidance in their developer portal whatsoever. I think it is just one of those telling aspects of how dysfunctional many companies are, and how their concerns are out of alignment with reality, and where they are investing their resources.
Every API should have some sort of branding page or area for their API operations--I even have a branding page. ;-) If you are looking for a healthy example to consider as a baseline of your branding page, take a look at Twitters branding page, which provides the essential building blocks you should be considering:
- Simple URL - Something easy to find, easily indexed by search engines, even a subdomain like Twitter does.
- Logos & Assets - Provide us with at least a logo for your company, if not a wealth of assets to put to use.
- Branding Guidelines - Offer up some structure, helping guide us, and show you've put some thought into branding.
- Link to Embeddables - If you have any buttons, badges, and widgets, point us to your embeddable resources.
- Link to Terms of Service - Provide us with a quick link to the terms of service as it applies to branding.
- Contact Information - Give me an email, or another channel for asking a question if I get confused at any time.
I do not agree with all of Twitter's branding enforcement, but I respect that they have set a bar, and provide the ecosystem with guidance. At the very least, it makes sure all of us are using the latest logo, and when done right it can help encourage consistency across every integration that is putting API resources to work. I find it hard time respecting branding concerns from companies who don't have a dedicated branding resource area for me to consult.
When done right, APIs extend the reach of any brand. Think about Twitter and Facebook sharing, and other embeddables. Most API consumers are more than happy to help extend your brand, but we are going to be lazy, and ALWAYS need guidance and things to copy / paste. At the very least, make sure you have the minimum viable branding assets and guidance like Twitter does, it really is the minimum bar for any API operating out there, and should not be ignored.
When processing the news for API.Report, and the over 150 areas of my API industry research, I spend a good deal of time looking for images to represent my stories, and the companies I'm covering. When looking for an image to best represent a company I always search google for "[company name] logo branding", and look for an official branding and logo guidelines page for a company--secondarily I switch over the image search if there is no official page available.
After a blog post, news piece, or research update goes live, I will sometimes receive a DM or email from a company asking me to update the logo, to a newer option than what I found via a Google search. I'm always happy to update the logo, and since my images are centrally stored on Amazon S3 it is pretty easy to do so. What I find interesting is that every company who actively polices their brand in this way never have an easy to find branding and logo area for their company and API operations.
I fully understand the need to police your brand and make sure your company's logo is represented in the best light, but what I don't understand is why they don't have a self-service branding area to help empower folks like me to do this on their own. It just seems like a lot of extra work that is unecessary or at least is something that you could minimize by providing a dedicated page where folks like me can find the most recent copy of your logo.
I spend a lot of time looking for good quality logos to represent the companies I track on and write stories about. I have a certain vision in my head about how I want company listings and detail pages to look across the API Evangelist network—something that takes a lot of work.
To support this vision, I spend a lot of time looking for logos. Sometimes you can find them in the header of a website, but often times they are poor quality, not configured to be standalone, or difficult to get at for any number of other reasons--making my work a lot tougher.
I published a new list of 819 companies who are doing interesting things with APIs that I call The API Stack. After publishing the project, Concur, one of the travel API providers listed, tweeted at me asking if I could replace their logo with a better quality one from their official logo page--I did so very quickly!
I sure love me a good logo and branding page for an API. It makes my life easier, by giving me a single place to go get high quality logos, without having to open up my image editor. I wish that more API platforms would have a well designed logo page like Concur.
I use both Bitly and Google shortened URLs to track activity across my networks. I don’t just track click throughs, I also track image impressions for many of my projects and partners. This usage of shortened URLs lets me quantity the scope of my network, and understand interest across the network in the form of impression and click-throughs.
After talking with Plot.ly about their embed strategy for API driven data visualizations, the topic of a sensible API branding has floated to the top of my story list again. I consider an APIs branding strategy to be an important building block that contributes to the politics of an API and its ecosystem (both internal and external). If an API branding strategy is too strict, it can turn developers off from using your API, but a well planned branding strategy that includes a healthy suite of embeddable tools can be a serious asset, and go a long way in satisfying internal concerns about brand integrity--which is major concern for companies when it comes to API deployment.
In the context of a basic API branding strategy, URL shorteners can provide a wealth of data about the scope of your API ecosystem, as well has help measure specific activity across deployments by your developers. You should be able to quantity the impressions and click throughs everywhere your API resources are put to use. Of course, a healthy API partner structure also allows for developers to opt out of tracking and possibly deploy white label solutions.
What does your branding strategy look like, and how to you measure the reach and activity across your API ecosystem?
One of the top five concerns I hear from companies considering APIs is regarding losing control of their brand. With APIs being about access to raw data and resources, companies immediately think that developers will extract the value, without any attribution or reference to the companies brand.
Even with this being a major concern, I see many APIs implement very poor branding guidelines, giving developers zero direction regarding how to properly provide attribution. This is a missed opportunity to not just protect the API providers brand, but actually extend it and increase its value.
With this in mind, I'm always on the lookout for good examples of API branding guidelines. One recent example I came across while monitoring my API Stack, is from the Active Network which provides activity and outdoor content via their APIs.
Active Network starts with a great explanation of why they provide branding guidelines:
At ACTIVE Network, we want you to be able to create fantastic applications with the ACTIVE Network APIs. At the same time, we don't want users to get confused about who is responsible for the data they are accessing, so we have some brand guidelines.
Next Active Network explains to developers why branding guidelines are important to their own users:
- The ACTIVE brand holds credibility in the mind of the customer. It serves as a seal of approval giving customers the confidence to transact through a trusted source
- As a consumer utility, ACTIVE.com® captures and records registration activity providing people with a record of their personal registration history if they need it at a future date
- Transacting for an ACTIVE powered activity, tells your customer who they need to call if they need help. ACTIVE’s standard of excellence provides customers with 24/7 support 365 days a year
Active Network also provides details on how to properly use their companies name (which I followed in my story), what attribution is required, and a complete branding kit for download as a zip file--containing the following key assets:
- Branding Guidelines in PDF Format
- Icon Image
- Powered by Logos
- Register Now Buttons
The Active Network Branding Guidelines is one of the better implementations I've come across. It provides a nice overview, with all of the details and assets needed to execute properly.
Even if you aren't concerned about your brand when it comes to your API, requiring some attribution from your developers will at least help you market and advertise your API, and potentially bring in new API consumers.
Managing API Terms of Service, Privacy, and Branding with Github
Since Github will allow document types other than code, such as markdown and PDF, it can make sense to use Github for managing the legal side of your API.
Using Github for the legal aspects of API operation will provide a level of transparency developers will appreciate, allowing them to download and store for their own records while being able to see the difference between each version, in a format that makes sense to them.
Just as with all other areas of an API, Github will allow you to completely manage the evolution of your API terms, privacy and branding in a way that is in sync with all the other technical and business building blocks of your API.
Google has made another step towards a more common API infrastructure in line with their API Discovery Service, API Explorer, and API Console by launching a single terms of service for all Google APIs.
Google has rewritten their terms from the ground up with the goal of making them easier to understand for application developers.
While more complex APIs like Youtube, Google Analytics, Google Adwords and Google Latitude still use their own terms of service. Over time, more APIs will be migrated to the new, centralized terms of service format.
If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.