{"API Road Map"}

Slack Nails The Reasons Why You Open Up And Share Your API Road Map

Many of the core areas of my API research, and the common building blocks of the API life cycle that I talk about regularly, often seem trivial to the technically inclined, or the purely business focused segments of my audience. To many, having a road map might be a thing you have when developing and deploying an API, but really doesn't matter if you share publicly. I'd say, with technical folks they often don't even think of it, with the more business focused individuals often deliberately choose not to, seeing it as giving away too much information to your competition. 

I think Slack nails the reason why you want to open up and share your API road map. I can talk about this kind of stuff until I'm blue in the face, but people just don't listen -- they need leadership like Slack brings to the table. In their post today, they open with:

We know that being a developer is hard, and building on a platform is not a decision to be made lightly. Many platforms have burned developers and we frequently see that risk highlighted. This is our response.

They nail the the (often elusive) promise of the API ecosystem:

An ecosystem, a real platform, is shared. We are growing fast, but no one company alone could grow fast enough to meet the amount of potential in front of us. We are working hard, but no one team can work hard enough to meet the demand that lies before us all. Instead, we are building a platform where this potential, this demand, is shared. As we grow, developers are able to succeed with us; sharing our customers and joining us in changing the way people do work. In turn, our customers are delighted, new customers have even more reason to use Slack, and the cycle continues.

They nail the reality of the API ecosystem, and how it is a shared experience:

An ecosystem in its healthiest form creates a virtuous cycle. Platforms do fail. We’ll make mistakes, but we’re building for something much greater. We are building for a future where Slack is dwarfed by the aggregate value of the companies built on top of it. This is our success as a platform — when the value of the businesses built on top of us is, in sum, larger than we can ever be.

They connect the reality of an ecosystem with having a public road map:

So, today we’re sharing our platform product roadmap. It is a small step in equipping you to claim this opportunity with us. There are three major platform product themes to highlight: app discovery, interactivity and developer experience — you can see more on this card.

Slack doesn't stop there, and throw in having a idea showcase to help as well:

We’re also sharing what we’re calling an Ideaboard — a list of useful ideas that could be built into Slack apps per conversations we’ve had with our customers. [...] The goal of the Ideaboard is to continue this momentum by creating a bridge between our developer community and our customers’ needs.

As Slack mentions, this won't be perfect. They don't have all the answers. A public road map and idea board  might not ultimately make or break Slack as a platform, or ensure the community continues to evolve as a full blown ecosystem. Shit can go wrong at any point, but having a public road map, and active, truly contributing idea board, will go a long way to contributing to positive outcomes. 

If you aren't allowing input from your API community into your road map, truly considering this input as you craft your road map, and then share the resulting plan with your community, how can you ever expect them to stay in sync? It doesn't mean that Slack will listen to everything, and every developers opinion will be included in the road map. It will however, put Slack into a more open state of mind, and go a long way to set the right tone in the API ecosystem, building trust with the individuals and business who are building on their platform.

What tone has been set in the community around the APIs you provide? What is the tone in the communities you exist in as an API consumer? 

See The Full Blog Post


Managing The ClinicalTrials.gov Support, Feedback, And Roadmap Using Github

Each of the Adopta.Agency project runs as a Github repository, with the main project site running using Github Pages. There are many reasons I do this, but one of the primary ones is that it provides me with most of what I need to provide support for the project.

Jekyll running on Github pages gives me the ability to have a blog, and manage the pages for the project, which is central to support. Next I use Github Issues for everything else. If anyone needs to ask a question, make a contribution, or report a bug, they can do so using Github Issues for the repository

I even drive the project road map, and change log using Github Issues. If I tag something as roadmap, it shows up on the road map, and if I tag something as changelog, and it is a closed issue, it will show up on the change log--this is the feedback loop that will help me move the clinical trials API forward.

See The Full Blog Post


Microsoft Increases The Visibility Of Their API Driven Platform With A New Road Map

A road map for your API, is one of those essential building blocks that can go a long way in building trust with your API consumers. Sharing your plans, helps developers prepare for the future, and better plan for their own road maps, keeping everything potentially in sync. 

From my vantage point, a simple, up to date, easily found road map is a building block that benefits both API provider and consumer. Road maps help provider organize their plans, and figure out how they are going to communicate it with the ecosystem, then setting the overall tone for how API consumers will engaging with a platform--both good and bad.

During my regular monitoring of the space, I saw that Microsoft released a pretty slick "Cloud Platform Roadmap", which is yet another sign for me on how Microsoft is stepping up their cloud (API) game. Their interactive road map allows you browse the roadmap by areas like cloud infrastructure or Internet of Things (IoT), and see features that are recently available, public preview, in development, cancelled, or have been archived.

Beyond the core functionality of the road map, I'm impressed that they published a blog post telling why they did it, acknowledging that it will bring visibility into platform operations. Additionally there is a prominent button, providing an email address where you can send your suggestions for the road map, providing evidence of how a roadmap can contribute to the overall feedback loop for an API platform.

Overall, I like the simplicity of the Microsoft cloud platform road map, and it is definitely a healthy building block I'd encourage other API providers to consider offering as well. I'm going to make sure Microsoft's roadmap is one of the examples I cite along the API management line, as part of my overall API life cycle map. 

See The Full Blog Post


Using API Definitions To Help API Providers With Their API Design Roadmap

As I work to create Swagger API definitions for the almost 1000 companies in my API stack, I'm chasing an elusive definition of a complete Swagger definition for any API. Only a small portion of APIs I am defining using Swagger will reach an 80-90% completions status, in reality most will never be complete for reasons that are totally out of my control.

When it comes to crafting API definitions for public APIs, I may be able to get the API definition complete in the sense that it has all the paths, parameters, responses, definitions, and security configurations, but if the API itself is missing pieces--the API definition will always be incomplete (in perpetuity).

As I work to automate the questions I ask of Swagger definitions, helping me get to a more coherent definition of what is a complete Swagger definition, I can't help feel the need to offer API design tips to the API providers I am profiling. Honestly I have never considered myself a high quality API designer, I've been more business than tech, but I can't help pointing out the obvious stuff. 

I am still using my API definition tooling for my own goals around defining the API Stack, but because I'm building it all as APIs, I intend to open it up to others for analyzing their own API definitions, determining how complete they are, and potentially offering up tips on what could be done to improve them. A kind of self-service, API design tip API, that helps with some of the most common elements that are missing from API designs.

In 2015, API definitions are opening up a buffet of services that are courting API providers ranging from mocking and deployment, to monitoring and security. I don't see why API definitions couldn't also allow for professional API designers to help API providers evolve their APIs in a more constructive ways, from the outside-in. Using Swagger or API Blueprint, professional designers could easily provide suggestions for existing API providers and their designs, then give them potential suggestions that they could use in their API design road-map.

Anyhoo, food for thought!

See The Full Blog Post


Adding a Roadmap To FAFSA

I needed a place to keep track of all the things I will be working on around the FAFSA API project. To help me keep track as well as communicate to you, I've added a roadmap page to this project.

The FAFSA roadmap is generated from Github milestones, using JavaScript and the Github API. If you'd like to see the history of work, you can look at the issues as well as the commit history for the FAFSA project.

If you have anything you'd like to see get done, you can submit as an issue and I'll either add as milestone or find other way to make sure the work gets done.

See The Full Blog Post


City of Philadelphia Shares Its Open Data Roadmap

A roadmap is an essential part of a healthy API ecosystem. The transparency and communication that come with providing a roadmap for your API and open data initiative will go a long way in building trust with your community.

The City of Philadelphia is sharing its roadmap of data sets that it intends to open in the coming months, by providing a release calendar using cloud project management service Trello. In addition to seeing the datasets the city intends to release, you can also see any data sets that have already been published.

According to the open data roadmap, Philadelphia is releasing data on street closures, energy consumption, evacuation routes, campaign finance, bike racks, budgets, expenditures and city employee salaries to name just a few.

This type of transparency doesn’t just build trust with citizens and developers, it provides an incentive for the city government to deliver high quality public data, in a meaningful and timely manner. There is still a lot of work to be done once this data is available, in order to develop quality analysis, visualizations, other APIs and tools that can be used in mobile and web applications. But what Philly is doing is a great start.

The City of Philadelphia’s approach to its open data roadmap is good to see. It is something all cities should have, as well as all API owners. Your roadmap will set expectations within your community, guide your own initiatives and provide a healthy blueprint for moving your efforts forward.

See The Full Blog Post


Communicate Your API Roadmap with Github

When you operate an API, you need to make sure and communicate with your developer community about what your plans are for the future, so developers can plan their own roadmap, and keep in sync with the coming changes to the API.

In addition to issue management using Github, API providers can use Github to manage their roadmap using the milestones features of the social coding platform. Milestones can be directly related to issues or can be larger goals around where you intend to take your API.

Milestones give developers insight into what the plans are the future of an API, using just a title, description and target date. Milestones are one of the simplest aspects of an API, but can go a long way in creating goodwill with your developers.

API providers have to balance transparency versus giving away information to competitors, something that will take regular consideration. A transparent roadmap for your API will let developers prepare properly, while also letting them know what features are coming in the future--eliminating the possibility of competing with your own ecosystem.

Consider what you can include in your Github roadmap, and using Github for issue management.

See The Full Blog Post


This Week Is First Milestone in White House Roadmap for an API Driven Digital Strategy

It will be 3 months since the White House CiO Steven VanRoekel released a federal API strategy, entitled "Digital Government: Building a 21st Century Platform to Better Serve the American People", part of the Executive Order 13571, directing all federal departments and agencies to make open data, content and web APIs the new default.

This Thursday, August 23rd 2012 will be the first major milestone for departments and agencies, where they should have met two goals:

  • 2.1 - Engage with customers to identify at least two existing major customer-facing services that contain high-value data or content as first-move candidates to make compliant with new open data, content, and web API policy
  • 7.1 - Engage with customers to identify at least two existing priority customer-facing services to optimize for mobile use

I’ve been monitoring 246 departments and agencies and so far three have released drafts of their strategy:

Department of Commerce
Department of Education (ED)
United States Agency for International Development (USAID)

While the Department of Commerce and Department of Education have only published paragraphs discussing how they are engaging with users, the United States Agency for International Development (USAID) has identified three datasets for the web API portion and two optimized for mobile use. All three have published their digital strategy in HTML, XML and JSON formats, meeting the requirements of "machine readable by default".

I anticipate we’ll see many more agencies releasing their digital strategies this week, but there is no way to tell how many agencies will be able to get on board with the CIO’s strategy in time. No matter what, the next 3 months will be critical time for APIs in Washington DC, not just because of the presidential election, but the end of November will be the next milestone where agencies are expected to have established an agency-wide governance structure for developing and delivering digital services via web APIs.

See The Full Blog Post


How Open Should We Be With Our API Road-maps?

I just finished reading two great posts about battles within API ecosystems.Convoluted TOS and "Open" APIs Will Be the Death of Us by Shion Deysarkar and Topify to Go Dark as Twitter Claims Another Dev Victim by Louis Gray. I recommend you read, and form your own opinion.

I'm totally behind Shion in, ..arguing that the breaching parties (i.e. the developers holding the API key) should not be held in contempt of court, as it were. When it comes to terms of service disagreements, there needs to be more discussion.

I also feel Topify's pain in their decision to, ..shut down the service, rather than chasing after Twitter's continued meandering API road-map. This makes it very difficult to build a business on Twitters API.

I am the biggest advocate for the developer when it comes to these ecosystems battles. API developers often deliver on the promise of an API, but seldom see the reward.

However I also feel the pain of API owners. How are you supposed to have an API that delivers true value, is sustainable, makes all your developers happy, and have terms of service and a roadmap that is all knowing and sees into the future, and promises never to step on your developers toes.

I see both sides of the argument, however I feel much of the trouble Twitter and other API owners run into, is the result of not properly sharing its roadmap with developers. If Twitter shared its road-map earlier, and more consistently with its developers, and also allowed feedback periods before launching, I think there would a lot less backlash--even if the community didn't always win 100% in the resulting decision.

How "open" an API owner is with their road-map obviously is entirely up to them. They have trade secrets to protect, and many other considerations when managing a roadmap. However you should identify a consistent time frame in which to give the developer community a heads up about what is happening. Something they can get used to, count on. Of course there will most likely be partners you share your road-map with before sharing it with your developer ecosystem. And don't forget to make sure to consider the press and blogosphere in this road-map release cycle. The press can be the first to bring up an issue, and ultimately end up being the bullhorn for developer grievances.

Also, if your platform has a accompanying web application, you will have to consider the linkage between its road-map and your API road-map. How do features you plan to release impact your developer community? When should they be informed about your companies plans for new products and features?

Rather than being polarized about these API ecosystem battles I hear about, I'm trying to put on my product managers hat, and find a balanced approach to solving. I don't think there is one single solution to make developers feel warm & fuzzy about integrating with APIs, and each industry or API sector may be different. But I think many of these problems can be addressed through early and consistent sharing of our API road-maps, which will truly make our APIs more open.

See The Full Blog Post