{"API Road Map"}

An Introduction To Github For API Providers

I have had a number of requests from folks lately to write more about Github, and how they can use the social coding platform as part of their API operations. As I work with more companies outside of the startup echo chamber on their API strategies I am encountering more groups that aren't Github fluent and could use some help getting started. It has also been a while since I've thought deeply about how API providers should be using Github so it will allow me to craft some fresh content on the subject.

Github As Your Technical Social Network
Think of Github as a more technical version of Facebook, but instead of the social interactions being centered around wall posts, news links, photos, and videos, it is focused on engagement with repositories. A repository is basically a file folder that you can make public or private, and put anything you want into it. While code is the most common thing put into Github repositories, they often contain data file, presentations, and other content, providing a beneficial way to manage many aspects of API operations.

The Github Basics
When putting Github to use as part of your API operations, start small. Get your profile setup, define your organization, and begin using it to manage documentation or other simple areas of your operations--until you get the hang of it. Set aside any pre-conceived notions about Github being about code, and focus on the handful of services it offers to enable your API operations.

  • Users - Just like other online services, Github has the notion of a user, where you provide a photo, description, and other relevant details about yourself. Avoid making a user accounts for your API, making sure you show the humans involved in API operations. It does make sense to have a testing, or other generic platform Github users accounts, but make sure your API team each have their own user profile, providing a snapshot of everyone involved.  
  • Organizations - You can use Github organizations to group your API operations under a single umbrella. Each organization has a name, logo, and description, and then you can add specific users as collaborators, and build your team under a single organization. Start with a single repository for your entire API operations, then you can consider the additional organization to further organize your efforts such as partner programs, or other aspects of internal API operations.
  • Repositories - A repository is just a folder. You can create a repository, and replicate (check out) a repository using the Github desktop client, and manage its content locally, and commit changes back to Github whenever you are ready. Repositories are designed for collaborative, version controlled engagements, allowing for many people to work together, while still providing centralized governance and control by the designated gatekeeper for whatever project being managed via a repository--the most common usage is for managing open source software.
  • Topics - Recently Github added the ability to label your repositories using what they call topics. Topics are used as part of Github discovery, allowing users to search using common topics, as well as searching for users, organizations, and repositories by keyword. Github Topics is providing another way for developers to find interesting APIs using search, browsing, and Github trends.
  • Gists - A GitHub service for managing code snippets that allow them to be embedded in other websites, documentation -- great for use in blog posts, and communication around API operations.
  • Pages - Use Github Pages for your project websites. It is the quickest way to stand up a web page to host API documentation, code samples, or the entire portal for your API effort.
  • API - Everything on the Github platform is available through the Github API. Making all aspects of your API operations available via an API, which is the way it should be.

Managing API Operations With Github
There are a handful of ways I encourage API providers to consider using Github as part of their operations. I prefer to use Github for all aspects of API operations, but not every organization is ready for that--I encourage you to focus in these areas when you are just getting going:

  • Developer Portal - You can use Github Pages to host your API developer portal--I recommend taking a look at my minimum viable API portal definition to see an example of this in action.
  • Documentation - Whether as part of the entire portal or just as a single repository, it is common for API providers to publish API documentation to Github. Using solutions like ReDoc, it is easy to make your API documentation look good, while also easily keeping them up to date.
  • Code Samples w/ Gists - It is easy to manage all samples for an API using Github Gists, allowing them to be embedded in the documentation, and other communication and storytelling conducted as part of platform operations.
  • Software Development Kits (SDK) Repositories - If you are providing complete SDKs for API integrations in a variety of languages you should be using Github to manage their existence, allowing API consumers to fork and integrate as they need, while also staying in tune with changes.
  • OpenAPI Management - Publish your APIs.json or OpenAPI definition to Github, allowing the YAML or JSON to be versioned, and managed in a collaborate environment where API consumers can fork and integrate into their own operations.
  • Issues - Use Github issues for managing the conversation around integration and operational issues.
  • Road Map - Also use Github Issues to help aggregate, collaborate, and evolve the road map for API operations, encouraging consumers to be involved.
  • Change Log - When anything on the roadmap is achieved flag it for inclusion in the change log, providing a list of changes to the platform that API consumers can use as a reference.

Github is essential to API operations. There is no requirement for Github users to possess developer skills. Many types of users put Github to use in managing the technical aspects of projects to take advantage of the network effect, as well as the version control and collaboration introduced by the social platform. It's common for non-technical folks to be intimidated by Github, ad developers often encourage this, but in reality, Github is as easy to use as any other social network--it just takes some time to get used to and familiar it.

If you have questions about how to use Github, feel free to reach out. I'm happy to focus on specific uses of Github for API operations in more detail. I have numerous examples of how it can be used, I just need to know where I should be focusing next. Remember, there are no stupid questions. I am an advocate for everyone taking advantage of Github and I fully understand that it can be difficult to understand how it works when you are just getting going. 

See The Full Blog Post


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