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 defining not just their APIs, but their schema, and other moving parts of their API operations.

Reviewing The Department Of Veterans Affairs New Developer Portal

I wanted to take a moment and review the Department Of Veterans Affairs (VA) new developer portal. Spending some time considering at how far they’ve come, what they published so far, and brainstorm on what the future might hold. Let me open by saying that I am working directly and indirectly with the VA on a variety of paid projects, but I’m not being paid to write about their API effort–that is something I’ve done since I worked there in 2013. I will craft a disclosure to this effect that I put at the bottom of each story I write about the VA, but I wanted to put out there in general, as I work through my thoughts on what is happening over at the VA.

The VA Has Come A Long Way I wanted to open up this review with a nod towards how far the VA has come. There have been other publicly available APIs at the VA, as well as a variety of open data efforts, but the VA is clearly going all in on APIs with this wave. The temperature at VA in 2013 when it came to APIs was lukewarm at best. With the activity I’m seeing at the moment, I can tell that the temperature of the water has gone way up. Sure, the agency still has a long way to go, but from what I can tell, the leadership is committed to the agencies API journey–something I have not seen before.

Developer.VA.Gov Sends The Right Signal It may not seem like much, but providing a public API portal at developer.va.gov sends a strong signal that the VA is seriously investing in their API effort. I see a lot of API programs, and companies who have a dedicated domain, or subdomain for their API operations are always more committed than people who make it just a subsection of their existing website, or existing as a help entry in a knowledge-base. It is important for federal agencies to have their own developer.[domain].gov portal that is actively maintained–which will be the next test for the VA’s resolve, keeping the portal active and growing.

The General Look And Feel Of The Portal I like the minimalist look of the VA developer portal. It is simple. Easy on the eyes. I feel like the “site is currently under development” is unnecessary, because this should never cease to be. I like the “an official website of the United States government”, it is clean, and official looking. I’m happy to see the “Get help from Veterans Crisis Line”, and is something that should be on any page with services, data, or content for veterans. I like the flexible messaging area (FMA), where it says “Put VA Data to Work”. I’d like to see this section become an evolving FMA, with a wealth of messages rolling through it, educating the ecosystem about what is happening across the VA developer platform at any given moment.

Getting Started And Learning More The learn more about VA APIs off the FMA area on home page drops me into benefits API overview, which happens to be the first category of APIs on the documentation page. I recommend isolating this to its own “getting started” page, which provides an overview of how to get started across all APIs. Providing background on the VA developer program, as well as the other building blocks of getting started with APIs, like requesting access, studying the API documentation, and the path to production for any application you are developing. The getting started for the VA developer portal should be a first class citizen, with its own page, and a logical presentation of exactly the building blocks developers will need to get started–then they can move onto documentation across all the API categories.

There Are Valuable APIs Available Once you do actually begin looking at the API documentation available within the VA developer portal, you realize that there are truly valuable APIs available in there. Don’t get me wrong, the Arlington National Cemetery API is important, which has been the only publicly available API from the VA for several years, but when I think about VA APIs, I’m looking for resources that make a meaningful and significant impact on a vets life today:

• Benefits Intake - Veterans Benefits Administration (VBA) document uploads.
• Appeals Status - Enables approved organizations to submit benefits-related PDFs and access information on a Veteran’s behalf.
• Facilities API - Use the VA Facility API to find relevant information about a specific VA facility. For each VA facility, you’ll find contact information, location, hours of operation and available services.
• Veterans Health API - [There is no concise description for this API, and what is there needs some serious taming, and pulling out as part of the portal.]
• Veteran Verification - We are working to give Veterans control of their information – their service history, Veteran status, discharge information, and more – and letting them control who sees it.

One minor thing, but will significantly contribute to the storytelling around VA APIs, is the consistent naming of APIs. Notice that only two of them have API in the title. I’m really not advocating for API to be in the title or not in the title. I am really advocating for consistency in naming, so that storytelling around them flows better. I lean towards using API in each title, just so that their titles in the documentation, OpenAPI contract behind, and everywhere these APIs travel are consistent, meaningful, and explain what is available.

I like the organizing of APIs into the three categories of benefits, facilities, and health. I’d say veteran verification is a little out of place. Maybe have a veteran category, and it is the first entry? IDK. I’m thinking there needs to be a little planning for the future, and what constitutes a category, and some guidance on how things are defined, broken down, and categories, so that there is some thought put into it the API catalog as it grows. A little separation of concerns in categorization, that can maybe begin to contribute the overall microservices strategy across the VA.

The Path To Production For Alpha API Clients I like the path to production information for alpha API clients, I felt like it should be its own dedicated page, as one building blocks of the getting started section. However, once I started scrutinizing, it seemed like it was a separate process potentially for each individual API or category of APIs. If it can be a standalone item, I’d make it one, and link to it from each individual API category, or individual API. It it can’t be, I’d figure out to make it an expandable section, or subsection of the docs. It isn’t something I want to have to scroll through when working with an API and its documentation. Sure, I want to be aware of it, and be able to understand it as part of on-boarding, and revisiting it at a later date, but I don’t need it to be part of the core documentation page–I just want to get at the interactive API documentation.

Self-Service Signup The process for signing up seems smooth. I haven’t been approved for access, and the review process makes a lot of sense. I’ll invest time in a separate story taking a look at the signup and on-boarding process, as well as the path to production flow for API clients, but I wanted to lightly reference as part of the review. I’d say the one confusing piece was leaving the website for the signup form, and then being dropped back at https://www.oit.va.gov/developer/, without much of any information about what was happening. It was a little jarring, and the overall flow, and process needs some smoothing out. I get that we are just getting started here, so I’m too worried about this–I just wanted to make a note of it.

The Essentials Are There Overall, the essentials are present at the VA developer area. It is a great start, and has the making of a good developer API portal. It just isn’t very mature, and you can tell things are just getting started. You can signup, get at API documentation, and understand what it takes to build an application on top of VA API resources. Adding to, refining, and further polishing what is there will take time, so I do not want to be too critical of what the VA has published–it is a much better start than I’ve seen out of other federal agencies.

There are some other random items I’d like to reference, as well as brainstorm a little on what I’d like see invested in next, helping ensure the VA API portal provides what it needed for developers to be successful:

• Terms of Service - It is good to see the basics of the TOS, and privacy policy there. I’d like to see more about privacy, security, and service level agreements (SLA).
• Use Of GitHub Issues - I like the submission GitHub issues to request production access, and think it is a healthy use of GitHub issues forms, and is something the brings observability to the on-boarding process across the community.
• Email Support - Beyond using GitHub issues for support and on-boarding, I see [email protected] a lot across the site. I get why you want to be at the center of things, but email support should be made generic, and enable group ownership of the email support workflow.
• Road Map - I’d like to see a roadmap of what is being planned, as well as a change log for what has already been accomplished.
• Frequently Asked Questions - I’d like to see an FAQ page, with questions and answers broken down by category, allowing me to browse some of the common questions as I’m getting up to speed.
• Code Samples & SDKs - I’d like to see some more code samples in a variety of programming languages, either baked into the interactive documentation, or available on its own SDK / Code Libraries pages. I get if the VA doesn’t want to get in the business of doing this, but with an OpenAPI core, there are more options available out there to generate code samples, libraries, and SDKs. I think this vets API client effort needs to be pulled onto a code samples and SDKs page, and there be more investment in projects like this.
• OpenAPI Download - I’d like to see a clear icon or button for downloading the OpenAPI 3.0 contract for each of the available APIs. I want to be able to use the OpenAPI definition for more than just documentation.
• OpenAPI 3.0 - I’m very happy to see OpenAPI 3.0 powering the API documentation, which I think is a little detail that shows the VA API team has been doing their homework.
• Postman Collections - I’d like to see a Run in Postman button at the top right corner of each API’s documentation, allowing me to quickly load up each API into my Postman API integration and development environment.
• Communications - I’d like to see a blog, a Twitter account, and emphasis on the VA Github account. As an API consumer I’d like to see that someone is home besides [email protected], and be able to have regular asynchronous conversations, and may engage synchronously during API office hours, or other format.

I’ll stop there. I have endless more ideas of what I’d like to see in the VA developer portal, but I’m just happy to see such a clean, informative portal up and running at developer.va.gov. I’m stoked they are working on delivering real APIs that offer value to the Veteran–that is why we are doing all of this, right? I’m curious to learn about what other APIs already exist and can just be hung within this portal, as well as what APIs are planned for the immediate road map. While there are still missing parts and pieces, what they’ve published is a damn fine start to the VA developer program.

Next, I’m going to do a deep dive into what I’d like to see in the getting started page, as well as the path to production guidance. I’d also like to do some deep thinking on the production application (regular) check-in and review processes. I have a short list of concepts I want to flesh out, and questions I would like to answer in future posts. I just wanted to make sure I took a moment to review the VA’s hard work on their new developer portal. The publishing of their developer portal marks a significant milestone in the agency’s API journey, marking the spot where their API platform is beginning to shift into a higher gear.

• Details

For Every Competitor You Keep Out Of Your API Docs You Are Keeping Twenty New Customers Out

It is interesting for me to still regularly come across so many API providers who have a public API portals, but insist on keeping most of their documentation behind a login. Stating that they are concerned with competitors getting access to the design of their API and the underlying schema. Revealing some indefensible API business models, and general paranoia around doing business on the web. Something that usually is a sign for me of a business that is working really hard to maintain a competitive grip within an industry, without actually having to do the hard work of innovating and moving the conversation forward.

Confident API providers know that you can put your API documentation out in the open, complete with schema, without giving away the farm. If your competition can take your API design, and underlying schema, and recreate your business–you should probably go back to the drawing board, and come up with a new business idea. Your API and schema definition is not your business. I’ve used this comparison may times–your API docs are like a restaurant menu. Can you imagine restaurants that kept them hidden until they were sure you are going to be a customer? If you think that your competition can read your menu and recreate all your dishes, then you won’t be in business very long, because your dishes probably weren’t that special to begin with.

For every competitor you keep out of your API documentation, you are keeping twenty new customers out as well. I’m guessing that your savvy competitors are going to be able to get in anyways with a fake account, or otherwise. Don’t waste your time on hiding your API and keeping it out of the view of your potential customers–invest your energy in making sure your APIs kick ass. To use the restaurant analogy again, make sure ingredients are the best, and your processes, and your service are top notch. Don’t make your menu hard to get, it just shows how out of touch you are with the mainstream world of APIs, and your worst fears will come true–someone will come along and do what you do, but even better, and you will become irrelevant.

Be proud of your APIs, and publish them prominently in your API portal. Make sure you have a OpenAPI definition handy, driving your documentation, tests, monitors, and other elements of your operations. Also make sure you have Postman Collections available, allowing your API definition to be portable and importable into the Postman client, allowing consumers to get up and running making calls in minutes, not hours or days. Get out of the way of your API consumers, don’t put up unnecessary, outdated obstacles in their way. I know that you feel you know best because you’ve been doing this for so long, and know your industry, but the world is moving on, and APIs are about doing business on the web in a much more open, accessible, and self-service way. If you aren’t moving in this direction, I’m guessing you won’t be doing what you do for much longer, because someone will come along who can move faster and be more open.

• Details

REST and gRPC Side by Side In New Google Endpoints Documentation

Google has been really moving forward with their development, and storytelling around gRPC. Their high speed to approach to doing APIs that uses HTTP/2 as a transport, and protocol buffers (ProtoBuf) as its serialized message format. Even with all this motion forward they aren’t leaving everyone doing basic web APIs behind, and are actively supporting both approaches across all new Google APIs, as well as in their services and tooling for deploying APIs in the Google Cloud–supporting two-speed APIs side by side, across their platform.

When you are using Google Cloud Endpoints to deploy and manage your APIs, you can choose to offer a more RESTful edition, as well as a more advanced gRPC edition. They’ve continued to support this approach across their service features, and tooling, by now also documenting your APIs. As part of their rollout of a supporting API portal and documentation for your Google Cloud Endpoints, you can automatically document both flavors of your APIs. Making a strong case for considering to offer both types of APIs, depending on the types of use cases you are looking to solve, and the types of developers you are catering to.

In my experience, simpler web APIs are ideal for people just getting going on their API journey, and will accommodate the evolution of 60-75% of the API deployment needs out there. Where some organizations further along in their API journey, and those providing B2B solutions, will potentially need higher performance, higher volume, gRPC APIs. Making what Google is offering with their cloud API infrastructure a pretty compelling option for helping mature API providers shift gears, or even helping folks understand that they’ll be able to shift gears down the road. You get an API deployment and management solution that simultaneously supports both speeds, but also the other supporting features, services, and tooling like documentation delivers at both speeds.

Normally I am pretty skeptical of single provider / community approaches to delivering alternative approaches to APIs. It is one of the reasons I still hold reservations around GraphQL. However with Google and gRPC they have put HTTP/2 to work, and the messaging format is open source. While the approach is definitely all Google, they have embraced the web, which I don’t see out of the Facebook led GraphQL community. I still questions Google’s motives, not because they are up to anything shady, but I’m just skeptical of EVERY company’s motivations when it comes to APIs. After eight years of doing this I don’t trust anyone to not be completely self serving. However, I’ve been tuned into gRPC for some time now and I haven’t seen any signs that make me nervous, and they keep delivering beneficial features like they did with this documentation, keeping me writing stories and showcasing what they are doing.

• Details

Having A Developer.[YourDomain] Is Clear Differentiator In The API Game

I am profiling US, UK, French, and German banks as part of some research I am doing for Streamdata.io. I am profiling how far along in the API journey these banks are, and one clear differentiator for me is whether a bank has a developer.[bankdomain] subdomain setup for their APIs or not. The banks that have a dedicated subdomain for their API operations have a clear lead over those who do not. The domain doesn’t do much all by itself, but it is clear that when a bank can get this decision made, many of the other decisions that need to be made are also happening in tandem.

This isn’t unique just to banking. This is something I’ve written about several times over the years, and remains constant after looking at thousands of APIs over the last eight years. When a company’s API presence exists within the help section of their website, the API is almost always secondary to the core business. When a company relies on a 3rd party service for their API and developer presence, it almost always goes dormant after a couple months, showing that APIs are just not a priority within the company. Having a dedicated subdomain, landing page, and set of resources dedicated to doing APIs goes a long way towards ensuring an API program gains the momentum it needs to be successful within an organization, and industry.

I know that having a dedicated subdomain for API operations seems like a small thing to many folks. However, it is one of the top symptoms of a successful API in my experience. Making data, content, and algorithms available in a machine readable way for use in other applications by 3rd party via the web is something every company, organization, institution, and government agency should be doing in 2018. It is the next iteration of the web, and is not something that should be a side project. Having a dedicated subdomain demonstrates that you understand this, and an API won’t just be the latest trend at your organization. Even if your APIs are entirely private in the beginning, having a public portal for your employees, partners, and other stakeholders will go along way towards helping you get the traction you are looking for in the API game.

• Details

API Life Cycle Basics: Portal

A coherent strategy to delivering and operating API portals is something that gets lost in a number of the API operations I am asked to review. It is also one of the more interesting aspects of the successful strategies I track on, something that when done right, can become a vibrant source of information, and when done wrong, can make an API a ghost town, and something people back away from when finding. As part of my research I think a lot about how API portals can be used as part of each APIs lifecycle, as well as at the aggregate levels across teams, within groups, between partners, and the public.

The most common form of the API portal is the classic public developer portal you find with Twitter, Twilio, Facebook, and other leading API pioneers. These portals provide a wealth of healthy patterns we can emulate, as well as some not so healthy ones. Beyond these public portals, I also se other patterns within the enterprise organizations I work with, that I think are worth sharing, showing how portals aren’t always just a single public destination, and can be much, much more.

• Individual Portals - Considering how developers and business users can be leverage portals to push forward conversations around the APIs they own and are moving forward.
• Team Portals - Thinking about how different groups and teams can have their own portals which aggregate APIs and other portals from across their project.
• Partner Portals - Leveraging a single, or even partner specific portals that are public or private for engaging in API projects with trusted partners.
• Public Portal - Begin the process of establishing a single Mutual of Omaha developer portal to provide a single point of entry for all public API efforts across the organization.
• Pipeline Integration - How can BitBucket be leverage for deploying of individual, team, partner, and even the public portal, making portals another aspect of the continuous deployment pipeline.

Portals can be used as the storage for the central truth of OpenAPI, and their JSON schema. They can be where documentation, coding, tooling, and other stops along the life cycle live. They also provide for an opportunity for decentralization of API deployment, but done in a way that can be evolved alongside the existing CI/CD evolution occurring within many organization, as well as aggregated and made available as part of company wide public, partner, or private discovery portals. Portals, can be much more than just a landing page, and can act as a doorway to a vibrant ecosystem within an organization.

I admit, it can be tough to turn a landing page for a portal into an active source of information, but with the right investment over time, it can happen. I maintain almost 200 separate portals as part of my work as the API Evangelist. Not all of them are active and vibrant, but they all serve a purpose. Some are meant to be static and never changing, with others being more ephemeral and meant to eventually go away. While others, like the home page for each stop along my API life cycle research staying active for almost eight years now, providing a wealth of information on not just a single APIs, but an entire industry.

• Details

The Transit Feed API Is A Nice Blueprint For Your Home Grown API Project

I look at a lot of APIs. When I land on the home page of an API portal, more often than not I am lost, confused, and unsure of what I need to do to get started. Us developers are very good at complexifying things, and making our APIs implementations as messy as our backends, and the API ideas in our heads. I suffer from this still, and I know what it takes to deliver a simple, useful API experience. It just takes time, resources, as well as knowledge to it properly, and simply. Oh, and caring. You have to care.

I am always on the hunt for good examples of simple API implementations that people can emulate, that aren’t the API rockstars like Twilio and Stripe who have crazy amounts of resources at their disposal. One good example of a simple, useful, well presented API can be found with the Transit Feeds API, which aggregates the feeds of many different transit providers around the world. When I land on the home page of Transit Feeds, I immediately know what is going on, and I go from home page to making my first API call in under 60 seconds–pretty impressive stuff, for a home grown API project.

While there are still some rough edges, Transit Feeds has all the hallmarks of a quality API implementation. Simple UI, with a clear message about what it does on the home, but most importantly an API that does one thing, and does it well–providing access to transit feeds. The site uses Github OAuth to allow me to instantly sign up and get my API key–which is how ALL APIs should work. You land on the portal, you immediately know what they do, and you have your keys in hand, making an API call, all without having to create yet another API developer account.

The Transit Feed API provides an OpenAPI for their API, and uses it to drive their Swagger UI API documentation. I wish the API documentation was embedded onto the docs page, but I’m just thankful they are using OpenAPI, and provide detailed interactive API documentations. Additionally, they have a great updates page, providing recent site, feed, and data updates across the project. To provide support they wisely use Github Issues to help provide a feedback loop with all their API consumers.

It isn’t rocket surgery. Transit Feed makes it look easy. They provide a pretty simple blueprint that the rest of us can follow. They have all the essential building blocks, in an easy to understand, easy to get up and running format. They leverage OpenAPI and Github, which should be the default for any public API. I’d love to see some POST and PUT methods for the API, encouraging for more engagement with users, but as I said earlier, I’m pretty happy with what is there, and just hope that the project owners keep investing in the Transit Feed API. It provides a great example for me to use when working with transit data, but also gives me a home grown example of an API project that any of my readers could emulate.

• Details

The Transit Feed API Is A Nice Blueprint For Your Home Grown API Project

I look at a lot of APIs. When I land on the home page of an API portal, more often than not I am lost, confused, and unsure of what I need to do to get started. Us developers are very good at complexifying things, and making our APIs implementations as messy as our backends, and the API ideas in our heads. I suffer from this still, and I know what it takes to deliver a simple, useful API experience. It just takes time, resources, as well as knowledge to it properly, and simply. Oh, and caring. You have to care.

I am always on the hunt for good examples of simple API implementations that people can emulate, that aren’t the API rockstars like Twilio and Stripe who have crazy amounts of resources at their disposal. One good example of a simple, useful, well presented API can be found with the Transfit Feeds API, which aggregates the feeds of many different transit providers around the world. When I land on the home page of Transit Feeds, I immediately know what is going on, and I go from home page to making my first API call in under 60 seconds–pretty impressive stuff, for a home grown API project.

While there are still some rough edges, Transit Feeds has all the hallmarks of a quality API implementation. Simple UI, with a clear message about what it does on the home, but most importantly an API that does one thing, and does it well–providing access to transit feeds. The site uses Github OAuth to allow me to instantly sign up and get my API key–which is how ALL APIs should work. You land on the portal, you immediately know what they do, and you have your keys in hand, making an API call, all without having to create yet another API developer account.

The Transit Feed API provides an OpenAPI for their API, and uses it to drive their Swagger UI API documentation. I wish the API documentation was embedded onto the docs page, but I’m just thankful they are using OpenAPI, and provide detailed interactive API documentations. Additionally, they have a great updates page, providing recent site, feed, and data updates across the project. To provide support they wisely use Github Issues to help provide a feedback loop with all their API consumers.

It isn’t rocket surgery. Transit Feed makes it look easy. They provide a pretty simple blueprint that the rest of us can follow. They have all the essential building blocks, in an easy to understand, easy to get up and running format. They leverage OpenAPI and Github, which should be the default for any public API. I’d love to see some POST and PUT methods for the API, encouraging for more engagement with users, but as I said earlier, I’m pretty happy with what is there, and just hope that the project owners keep investing in the Transit Feed API. It provides a great example for me to use when working with transit data, but also gives me a home grown example of an API project that any of my readers could emulate.

• Details

API Life Cycle Basics: Portal

A coherent strategy to delivering and operating API portals is something that gets lost in a number of the API operations I am asked to review. It is also one of the more interesting aspects of the successful strategies I track on, something that when done right, can become a vibrant source of information, and when done wrong, can make an API a ghost town, and something people back away from when finding. As part of my research I think a lot about how API portals can be used as part of each APIs lifecycle, as well as at the aggregate levels across teams, within groups, between partners, and the public.

The most common form of the API portal is the classic public developer portal you find with Twitter, Twilio, Facebook, and other leading API pioneers. These portals provide a wealth of healthy patterns we can emulate, as well as some not so healthy ones. Beyond these public portals, I also se other patterns within the enterprise organizations I work with, that I think are worth sharing, showing how portals aren’t always just a single public desination, and can be much, much more.

• Individual Portals - Considering how developers and business users can be leverage portals to push forward conversations around the APIs they own and are moving forward.
• Team Portals - Thinking about how different groups and teams can have their own portals which aggregate APIs and other portals from across their project.
• Partner Portals - Leveraging a single, or even partner specific portals that are public or private for engaging in API projects with trusted partners.
• Public Portal - Begin the process of establishing a single Mutual of Omaha developer portal to provide a single point of entry for all public API efforts across the organization.
• Pipeline Integration - How can BitBucket be leverage for deploying of individual, team, partner, and even the public portal, making portals another aspect of the continuous deployment pipeline.

Portals can be used as the storage for the central truth of OpenAPI, and their JSON schema. They can be where documentation, coding, tooling, and other stops along the life cycle live. They also provide for an opportunity for decentralization of API deployment, but done in a way that can be evolved alongside the existing CI/CD evolution occurring within many organization, as well as aggregated and made available as part of company wide public, partner, or private discovery portals. Portals, can be much more than just a landing page, and can act as a doorway to a vibrant ecoystem within an organization.

I admit, it can be tough to turn a landing page for a portal into an active source of information, but with the right investment over time, it can happen. I maintain almost 200 separate portals as part of my work as the API Evangelist. Not all of them are active and vibrant, but they all serve a purpose. Some are meant to be static and never changing, with others being more ephermeral and meant to eventually go away. While others, like the home page for each stop along my API life cycle research staying active for almost eight years now, providing a wealth of information on not just a single APIs, but an entire industry.

• Details

API Deployment Templates As Part Of A Wider API Governance Strategy

People have been asking me for more stories on API governance. Examples of how it is working, or not working at the companies, organizations, institutions, and government agencies I’m talking with. Some folks are looking for top down ways of controlling large teams of developers when it comes to delivering APIs consistently across large disparate organizations, while others are looking for bottom ways to educate and incentivize developers to operate APIs in sync, working together as a large, distributed engine.

I’m approach my research into API governance as I would any other area, not from the bottom up, or top down. I’m just assembling all the building blocks I come across, then began to assemble them into a coherent picture of what is working, and what is not. One example I’ve found of an approach to helping API providers across the federal government better implement consistent API patterns is out of the General Services Administration (GSA), with the Prototype City Pairs API. The Github repository is a working API prototype, documentation and developer portal that is in alignment with the GSA API design guidelines, providing a working example that other API developers can reverse engineer.

The Prototype City Pairs API is a forkable example of what you want developers to emulate in their work. It is a tool in the GSA’s API governance toolbox. It demonstrates what developers should be working towards in not just their API design, but also the supporting portal and documentation. The GSA leads by example. Providing a pretty compelling approach to model, and a building block any API provider could add to their toolbox. I would consider a working prototype to be both a bottom up approach because it is forkable, and usable, but also top down because it can reflect wider organizational API governance objectives.

I could see mature API governance operations having multiple API design and deployment templates like the GSA has done, providing a suite of forkable, reusable API templates that developers can put to use. While not all developers would use, in my experience many teams are actually made up of reverse engineers, who tend to emulate what they know. If they are exposed to bad API design, they tend to just emulate that, but if they are given robust, well-defined examples, they will just emulate healthy patterns. I’m adding API deployment templates to my API governance research, and will keep rounding off strategies for successful API governance, that can work at a wide variety of organizations, and platforms. As it stands, there are not very many examples out there, and I’m hoping to pull together any of the pieces I can find into a coherent set of approaches folks can choose from when crafting their own approach.

• Details

Sorry Your API Effort Falls A Little Short For The APIs I Cover

I get a lot of emails from companies asking me to look at their APIs. Too many for a one person operation like me to consider. I have to be picky about the APIs I’m taking a look at, and over time I’ve developed a set of criteria for determining how much energy I will invest in an API. Usually within about 2-3 minutes I can tell if it is an API I will be diving in deeper, or I will just be walking away and moving on with my work.

The first thing that turns me off of an API is that it just isn’t interesting. I’ll land on the page and I can tell what it does, but it just doesn’t interest me. It doesn’t offer any value, or it is in a category that I’m just not eager to be thinking about and showcasing in my work. If an API doesn’t deliver value, and stand out as being interesting beyond the hundreds of other APIs I see each week, I’m just not going to stop and take notice. Sorry, it might be to others–don’t just take my opinion.

The next thing that keeps me from going deeper is I can’t tell what an API does. I’m always amazed at how much head scratching, clicking and reading I will do before I ever figure out what an API does. I’m pretty hard headed, so sometimes its me, but other times I’m just stuck at figuring out what is going on under the hood. Usually after about 3-5 minutes of struggling to understand what is happening, I will just walk away. It is unlikely that other folks will be investing more time than that, and the API will not last long in my experience.

After that, the biggest crime I see companies and organizations make is that they just do not invest enough into a dedicated portal, and the other supporting resources for their API. If someone sends me a link to their API and it is in the help or knowledge base section of their website, I know that they don’t really care about it, and won’t be investing much more into it. APIs shouldn’t be a side project for companies in 2017, they should be front and center, in their own dedicated portal, with a prominent link off the website navigation.

I try to always respond to emails I get from folks letting them know their API efforts fall short of what I’m expecting to see. I feel bad raining on their parade, but the bar is pretty high in 2017. Your API needs to stand out, deliver value, and be something you are investing in. Maybe my response will light the fire under your API operations, and at least get you reading my blog some more, and learning about what other API providers are doing. Then you can take some of what you’ve learned back to your organization and get to work building a first class API operation.

• Details

The API Portal Outline For A Project I Am Working On

I am working through a project for a client, helping them deliver a portal for their API. As I do with any of my recommendations with my clients, I take my existing API research, and refine it to help craft a strategy to meets their specific needs. Each time I do this it gives me a chance to rethink some of my recommendations I’ve already gathered, as well as learn from new types of projects. I’ve taken the building blocks from my API portal, as well as my API management research, and have taken a crack at organizing them into an outline that I can use to guide my current project.

Here is a walk through of the outline I’m recommending as part of a basic API portal implementation, to support a simple public API:

• Overview - / - Everything starts with a landing page, with a simple overview of what an API does.

Then you need some basics to help make on-boarding as frictionless as possible, providing everything an API consumer needs to get going:

• Getting Started - /getting-started/ - Handful of steps with exactly what is needed to get started.
• Authentication - /authentication/ - An overview of what type of authentication is used.
• Documentation - /documentation/ - Documentation for the APIs that are available.
• FAQ - /faq/ - Answer the most common questions.
• Code - /code/ - Provide code samples, libraries, and SDKs to get going.

Then get API consumers signed up, or able to login and get at their API keys as quickly as you possibly can:

• Sign Up - /developer/ - Provide a simple sign up for a developer account.
• Login - /developer/ - Allow users to quickly log back in after they have account.

Next, provide a wealth of communication and support mechanisms, helping make sure developers are aware of what is going on:

• Blog - /blog/ - A simple blog dedicated to sharing stories about the API.
• Support - /support/ - Offer up a handful of support channels like email and tickets.
• Road Map - /road-map/ - Provide a road map of what the future will hold for the API.
• Issues - /issues/ - Share what the known issues are for the API platform.
• Change Log - /change-log/ - Publish a log of everything that has changed with the platform.
• Status - /status/ - Provide a status page showing the availability of API services.
• Security - /security/ - Publish an overview of what security practices are in place.

Make sure your consumers know how to get involved at the right level, making plans, pricing, and partnership opportunities easy to find:

• Plans - /plans/ - Offer a single page with API access plans and pricing information.
• Partners - /partners/ - Share what the partnership opportunities are, as well as existing partners.

Then let’s take care of the legal side of things, making sure API consumers are fully aware of the TOS, and other aspects of operations:

• Terms of Service - /terms-of-service/ - Make the terms of service easy to find.
• Privacy - /Privacy/ - Publish a privacy statement for all API consumers.
• Licensing - /Licensing/ - Share the licensing for API, code, data, and other assets.

I also wanted to make sure I took care of the basics for the developer accounts, flushing out the common building blocks developers will need to be successful:

• Dashboard - /developer/dashboard/ - Provide a simple, comprehensive dashboard for developers.
• Account - /developer/account/ - Allow API consumers to change their account information.
• Applications - /developer/applications/ - Allow API consumers to add multiple applications, and receive API keys for each application.
• Plans - /developer/plans/ - If there are multiple plans, allow developers to change plans.
• Usage - /developer/usage/ - Show history of all API usage for API consumers.
• Billing - /developer/billing/ - Allow API consumers to add, update, and remove billing information.
• Invoices - /developer/invoices/ - Share a listing, as well as detail of all invoices for use.

Then I had a handful of other looser items that I wanted to make sure were here. Some of these will be for the second phase of developoment, but I want to make sure is on the list:

• Branding - /branding/ - Providing a logo, branding guidelines, and requirements.
• Embeddable - /embeddable/ - Share a handful of butts and widgets for use by consumers.
• Webhooks - /Webhooks/ - Publish details on how to setup and manage webhook notifications.
• iPaaS - /ipaas/ - Information on Zapier, and other iPaaS integration solutions that are available.
• Spreadsheets - /spreadsheets/ - Share any spreadsheet plugins or connectors that are available for integration.

That concludes what I’d consider to be the essential building blocks for an API. Sure, there are some more minor APIs that can operate on a bare bones version of this list, but for any API looking to conduct business at scale, I’d recommend considering everything on this list. It reflects what I find across the leading providers like Stripe and Twilio, and reflect what I like to see from an API provider when I am getting up and running using any API.

I have Jekyll templates for each of these building blocks, which use the Bootstrap UI for the layout. I am updating it for this project, then I will publish again as a set of forkable tools that anyone can implement. I’m going to publish a new API portal that runs as an interactive outline of essential building blocks, then creates new Github repository for a user, and publishes each of the selected components to the repo. Providing a buffet of API developer portal tools anyone can put to work for their API without much work.

• Details

Operating Your API Portal Using Github

Operating on Github is natural for me, but I am regularly reminded what a foreign concept it is for some of the API providers I’m speaking with. Github is the cheapest, easiest way to launch a public or private developer portal for your API. With the introduction of Github Pages, each Github repository is turned into a place to host any API related project. In my opinion, every API should begin with Github, providing a place to put your API definition, portal, and other elements of your API operations.

If you are just getting going with understand how Github can be used to support your API operations, I wanted to provide a simple checklist of the concepts at play, that will lead you being able to publish your API portal to Github.

• Github Account - You will need an account to be able to use Github. Anything you do on Github that is public will be free. You can do private portals on Github, but this story is about using it for a public API portal.
• Github Organization - I recommend starting an organization for your API operations, instead of under just a single users account. Then you can make the definition for the API the first repository, and possibly the portal your second repository you create.
• Github Repo - A Github repository is basically a folder on the platform which you can start the code, pages, and other content used as part of API operations.
• Github Pages - Each Github repository has the ability to turn on a public project site, which can be used as a hosting location for a developer portal.
• Jekyll - Github Pages allows any Github repository to become a website hosting location which you can access via your Github user account, or even provide an address using your own domain.

I recommend every API provider think about hosting their API portal on Github. The learning curve isn’t that significant to get up and running, and if your portal is public, it is free. You can version control, and leverage other key aspects of Github for evolving and managing your API portal. There are a growing number of examples of forkable API portals like from the GSA, or an interesting minimum viable API documentation template from my friend James Higginbotham (@launchany). Demonstrating that the practice is growing, with the number of healthy examples to build on diversifying.

If you need help understanding how to use Github for hosting your API developer portal, feel free to reach out. I am happy to see where I can help. Another thing to note is that this approach to running a Jekyll static website isn’t limited to Github. You can always start the project there, and move off to any Jekyll enabled hosting provider. I run my entire network of websites and API project this way, leveraging Github as my plan A, and AWS as my plan B, with a server image ready to go when I need. Github just provides a number of bells and whistles that make it much more usable, as well as something others can collaborate around, enjoying the network effects that come with using the platform.

• Details

A New Minimum Viable Documentation(MVD) Jekyll Template For APIs

I am a big fan of Jekyll, the static content management system (CMS). All of API Evangelist runs as hundreds of little Jekyll driven Github repositories, in a sort of microservices concert, allowing me to orchestrate my research, data, and the stories I tell across all of my projects. I recommend that API providers launch their API portals using Jekyll, whether you choose to run on Github, or anywhere else using the light-weight portable solution. I have several Jekyll templates I use to to fork and turn into new API portals, providing me with a robust toolbox for making APIs more usable.

My friend and collaborator James Higginbotham(@launchany) has launched a new minimum viable documentation (MVD) template for APIs, providing API provides with everything they need out of the gate when it comes to a presence for their API. The MVD solution provides you with a place for your getting started, workflows, code samples, reference material, with OpenAPI as the heartbeat–providing you with everything you need when it comes to API documentation. It all is an open source package available on Github, allowing any API provider to fork and quickly change the content and look and feel to match your needs. Which in my opinion, is the way ALL API documentation solutions should be. None of us should be re-inventing the wheel when it comes to our API portals, there are too many good examples out their to follow.

I know that Jekyll is intimidating for many folks. I’m currently dealing with this on several fronts, but trust me when I say that Jekyll will become one of the most important tools in your API toolbox. It takes a bit to learn the structure of Jekyll, and get over some of the quirks of learning to program using Liquid, but once you do, it will open up a whole new world for you. It is much more than just a static content management system (CMS). For me, it’s most significant strength has become as a data management system (DMS)??, with OpenAPI as the heart. I use Jekyll (and Github) for managing all my OpenAPI definitions, JSON and YAML files, and increasingly publishing my data sets in this way instead of relying on server-side technology. If you are looking for an new solution when it comes to your API portal, I recommend taking a look at what James is up to.

• Details

The GSA API Standards With A Working Prototype API And Portal

One way to help API developers understand API design is to provide them with a design guide, helping set a standard for how APIs should be designed across an organization or group. Another way to help developers follow best practices when it comes to API design is to provide them with a working example they can follow when developing their API(s). In my experience people learn API design best practices through following what they know–emulating what they see.

Hang on to that thought, cause now I’m going to blow your mind. Guess how API providers learn how to provide API design guide and working examples? By showcasing working examples of companies, institutions, and government agencies publishing API design guides, working APIs, and portal prototypes. So that other API providers can learn by example! BOOM! Mind blown. :-) An example of this can be found over at the General Service Administration (GSA), with their API standards guide, API prototype, and forkable API portal and documentation–complete with the essential API building blocks.

The GSA’s simple approach to providing a working example of their API standards is refreshing. They have taken an existing GSA data set and launched a prototype API, then they published the API in a complete, working API developer portal with all the essential building blocks of a basic API presence.

• Getting Started - What you need to get started with the API.
• Documentation - OpenAPI driven interactive API documentation.
• Schema - A reference of the fields / schema used for API responses.
• FAQ - Some basic questions about the API, and more importantly the API prototype.
• Contact Info - Using Github issues for support, with an accompanying email.

The whole things runs on Github so it is forkable. What is great, is that they also have the source code for the API on Github, essentially providing a working, forkable representation of what is expected in the GSA API design guide. This is how you plant seeds for consistent API design across an organization. An API design guide setting standard, with a working example of what you would like to see as the finished product.

I’m really getting into this approach to defining the API conversation within an organization. I’m working with a handful of large organizations right now to develop API prototypes, evolve my current API portal definition, as well as working to influence the GSA’s approach. If you aren’t familiar with the General Services Administration (GSA), a significant portion of their mission is dedicated to delivering technology services to the over 430 departments, agencies, and sub-agencies in the federal government. The GSA API design guide, prototype, and portal provide a working example other agencies can follow when defining, designing, deploying, and managing their API presence–important stuff.

• Details

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. 

• Details

The Tyk Wordpress API Portal

I am finally seeing more solutions available for API providers when it comes to publishing an portal for their API operations. I've long had my minimum viable API portal definition, which I recently deployed to support the Miami Open211 API, and I also wrote about AWS serverless approach to an API portal. Next up, is a WordPress solution from my API management partner Tyk.

The WordPress API portal solution has the following features:

• Automatic developer registration on Tyk when developers sign up in WP
• Configuration of API policies available for token registration
• Developers may request an access token for the available API policies
• Automatic or manual approval of key requests
• Storage of token (references) by name and API policy
• Revoking of tokens by developer
• Display usage statistics per key
• Request quota usage per key

All the basics you need when standing up a basic API operation. If WordPress is your go-to content management system, then it might make sense for you to think about API portal in these terms. The Swiss Federal Railways (SBB-CFF-FFS) is already using the plugin in production, and you can download the plugin on Github, or find it over at WordPress.org.

We need multiple versions of API portals like this, designed for every type of platform a company, organization, institution, and government agency might be already using as a default platform for their operations. This is why API management providers need to follow Tyk's lead and make sure your solution is API driven--practicing what you preach so that your API management solution can be integrated anywhere.

• Details

The AWS Serverless API Portal

I was looking through the Github accounts for Amazon Web Services and came across their Serverless API Portal--a pretty functional example of a forkable developer portal for your API, running on a variety of AWS services. It's a pretty interesting implementation because in addition to the tech of your API management it also helps you with the business side of things. 

The AWS Serverless Developer Portal "is a reference implementation for a developer portal application that allows users to register, discover, and subscribe to your API Products (API Gateway Usage Plans), manage their API Keys, and view their usage metrics for your APIs..[]..it also supports subscription/unsubscription through a SaaS product offering through the AWS Marketplace."--providing a pretty compelling API portal solution running on AWS.

There are a couple things I think are pretty noteworthy:

• Application Backend (/lambdas/backend) - The application backend is a Lambda function built on the aws-serverless-express library. The backend is responsible for login/registration, API subscription/unsubscription, usage metrics, and handling product subscription redirects from AWS Marketplace.
• Marketplace SaaS Setup Instructions - You can sell your SaaS product through AWS Marketplace and have the developer portal manage the subscription/unsubscription workflows. API Gateway will automatically provide authorization and metering for your product and subscribers will be automatically billed through AWS Marketplace
• AWS Marketplace SNS Listener Function (Optional) (/listener) - The listener Lambda function will be triggered when customers subscribe or unsubscribe to your product through the AWS Marketplace console. AWS Marketplace will generate a unique SNS Topic where events will be published for your product.

This is the required infrastructure we'll need to get to what I've been talking about for some time with my wholesale API and virtual API stack stories. Amazon is providing you with the infrastructure you need to set up the storefront for your APIs, providing the management layer you will need, including monetization via their marketplace. This is a retail layer, but because your infrastructure is setup in this way, there is no reason you can't sell all or part of your setup to other wholesale customers, using the same AWS marketplace.

I had AWS marketplace on my list of solutions to better understand for some time now, but the AWS Serverless Developer Portal really begins to connect the dots for me. If you can sell access to your API infrastructure using this model, you can also sell your API infrastructure to others using this model. I will have to set up some infrastructure using this approach to better flush out how AWS infrastructure and open templates like this serverless developer portal can help facilitate a more versatile, virtualized, and wholesale API lifecycle. 

There is a more detailed walkthrough of how to get going with the AWS Serverless Developer Portal, helping you think through the details. I am a big fan of these types of templates--forkable Github repositories, with a blueprint you can follow to achieve a specific API deployment, management, or any other lifecycle objective.

• Details

A More Distilled Version of An API Getting Started Page On The Home Page Of A Developer Portal

As I look through API portals, profiling the building blocks of successful API platform, I'm always looking for bite-size stories for my readers. I was working to complete my Instagram API definition, as part of my photo API research, and their getting started graphic caught my attention.

This three step getting started visual for Instagram is prominently available on the home page, providing a very distilled down version of what I recommend API providers usually accomplish with a dedicated getting started page.

The featured getting started area provides you with the link to register your application, and overview on authentication and authorization, and a link to all the endpoints, so you can start making requests. I am a big fan of there always being a dedicated getting started page for APIs that I am on-boarding with, but I am always a bigger fan when someone distills these building blocks into something that is way easier to understand, and execute--without all the blah blah blah.

I'm going to consider adding a feature getting started building block, in addition to having the dedicated page. When done right, I think they can accomplsh the same thing, but with one less click--reducing any friction we possibly can in the on-boarding process.

• Details

Making Sure The Latest API Pricing Update Is Available In A Developer Portal Messaging Area

I am spending a significant amount of time looking through the pricing pages for leading API providers, working to get a sense for some of the common approaches to API monetization in use across the space. Along the way I am finding some simple approaches from API providers that I wanted to share as bit-size API planning stories here on the blog.

After recently landing on the pricing page for identity service provider Auth0, I saw that they included a simple message and link to the latest blog post about API pricing changes. It is a simple, subtle, yet very prominent approach to making sure your API consumers are aware of pricing changes that may impact their integration. I recently wrote about providing a messaging area to reach developers upon platform login, but this approach from Auth0 is about providing relevant messaging no matter where you are at in the developer portal--not just at login.

Couple of lessons for me, extracted from this approach:

1. Prominent FMA - Providing a prominently placed, flexible messaging area, can help make sure your API consumers stay up to speed on the latest, when it comes to platform operations. 
2. Pricing Storytelling - Telling the story around each change in pricing is a critical aspect of operation. Publishing a story on your blog, syndicating out through your social channels, and prominent placement via a FMA is key.

This help rekenforce the fact that we should make sure to regularly communicating out our decisions around API monetization. Also making sure there is a saturation factor to our messaging, and that it is available via our blogs, Twitter, LinkedIn, and any other relevant page or channel used to reach API consumers.

I have a whole list of bit-size API monetization, pricing, and planning stories queued up. I will try to space them out, alongside other stories, but you will just have to suffer a little as I spend time expanding on my API monetization, and API plans research areas. 

• Details

Adding a Suggested API Definition for API Portals to My API Management Spec Collection

One layer I am working to add to my API research, are machine readable API definitions that I find, or generate from the APIs of the API service providers I keep an eye on. Within this new layer I'm aggregating these API the specs of the companies who are offering services within the emerging areas of the API sector.

The first area I've started aggregating is within API management. 3Scale was very forward leaning with their willingness to open up their API definitions for their own API management infrastructure APIs. These are API specs that describe all of the features of the 3Scale API management platform, and represent one possible blueprint that API management service providers could emulate.

I have four separate API definitions included from 3Scale on my new page, something that could be broken down further if it makes sense. I also just added a suggested API definition for API portals--crafted by the APIMATIC team. They thought my idea for defining a common set of definitions across the 17+ areas I monitor was an interesting cenough oncept, and was something they wanted to explore further with me.

Zeeshan Ejaz Bhatti of APIMATIC pulled together this spec:

This is just one potential starting point for providing a common interface for managing your API portal. Zeeshan feels that , if "API-Portals-as-a-Service", and other API management providers agreed on a common publish API format, it would benefit other API service providers like APIMATIC who are providing services to their customers via these API portals.

I agree with Zeeshan, and might play around adding an API facade for managing your API portal using Github + Jekyll, like I do with my standard API Portal template. This is all work in progress. Right now I am just aggregating the API definitions for API service providers that have APIs. In my opinion this layer of the API space will differentiate API service providers from each other, demonstrating which ones will actually scale in the fast growing the API economy.

Next I'm taking API monitoring services like Runscope and API Science, and aggregate their API definitions as part of my research.

• Details

Migrating To Version 2.0 Of API Evangelist Portal

It's been a couple years since I started providing public access to my APIs. Historically I haven't really been in the business of generating revenue from my APIs, it is more of a show than anything, but this is something I'm looking to change. This means I need to get my act together when it comes to API design, deployment, management, and monitoring, and practice what I preach.

This is the first step in that direction. I'm launching a new portal to support the handful of APIs I want to make available as part of API Evangelist. This is just a subset of the larger stack of APIs I am working on, but access to my APIs are universal, and one API key will get you access to almost all the APIs across my network. 

I would consider everything you find here BETA, unless stated otherwise. I'm working on way to certify my APIs as ready for production, differentiating the "in development", from the hardened APIs I"m not making changes to. If you have any questions, feel free to submit an issue via this portals Github repository, and I'll do my best to tackle. I'm rapidly evolving these APIs, and others, now that my platform is a little more stable, so come back often.

• Details

When Planning Your API Portal Do Not Hide APIs and Always Translate From IT To Something Humans Can Understand

While updating my APIs in higher education research this last week I came across an API portal I think tells an important story about an evolution in how we develop and maintain software. The current wave of web APIs that I cover has been working well because it has exposed a number of valuable resources, that once upon a time were only available in the realm of IT, making these resources accessible to a wider audience of developers, or even business users. 

This evolution has been slowly pulling back the curtain of IT, exposing more of it's inner workings, potentially simplifying, and decoupling valuable digital resources from legacy power structures. An important piece of this transformation is the translation of IT speak to language that the average human can understand, something that is playing out within API developer portals across companies, organizations, institutions, and government agencies. 

I touched on this subject with my work on the Environmental Protection Agency (EPA) Envirofacts API a couple weeks ago. With a little work I was able to expose a rich set of API resources, just by renaming the APIs, and hydrating some of the acronyms that were being used. While this is an example of the intersection of government IT power structures, it represents the same evolution.

As I was updating my university API work, I stumbled across the same evolution occurring at The Ohio State University. When you land on this API developer portal, you are given no signal that this contains course, and other valuable campus related APIs.

This API effort is born out of a classic IT lead project, and while it brings forward some healthy API patterns, it also carries forth the language and culture of IT. I am not saying the team behind the API portal is approaching their portal with intentional bias, these types of efforts are common, and often done by very well meaning groups, who only shortcomings are they don't think about reaching a widest audience possible. 

The idea that anyone should be able to land on an API portal, and be able to understand what is going on, is a foreign concept to many IT and developer groups. They build web service portals, system documentation, and other system doorways, thinking that other like-minded (IT and dev) folks will be coming there. They just aren't used to thinking that business leaders, researchers, data journalists, teachers, students, and any number of other folks might be coming there too.

Most groups that I come across like this, just need to be enlightened, and they will course correct. A smaller, but an often vocal group see no use in anyone outside the IT good ol boy club having access to resources--this is the old IT guard, and how power is protected. They will be gone soon, but for now you will have to just work around them. My goal is to just educate the API portal groups who are willing to listen, and stimulate API efforts from outside of IT lead groups when it is necessary, not to convert the critics. 

• Details

Quantifying A Minimum Viable API Footprint Definition As Real APIs.json Driven Portal

I wrote a post the other day laying out what I'd consider a minimum viable footprint for API operations. My vision of just exactly what an API is, has gone beyond just the technical, ever since I started API Evangelist back in July of 2010. Early on I saw this was more than just about the API endpoints, and documentation, code samples, and many other building blocks were essential to the success (or failure) of any API platform, area, or ecosystem.

This recent post was an attempt, here in 2015, to quantify what I would consider to be a minimum definition for API operation. After writing it I wanted to take another stab at actually creating a portal, that would stand up to the API rhetoric that I regularly produce. What better place to start, than my own personal master API stack, where I am working to get control over my own infrastructure. Once I got a version 1.0 definition, I forked it, and setup a default API portal that I am calling my demo APIs.json driven portal.

I have published to Github, a version of my minimum API footprint, which I'm using APIs.json an engine. After looking at 10,000K+ APIs, I have a pretty good idea of what I like to see. This is my interpretation of all that monitoring of the space--a distillation of what I've seen while reviewing APIs. It isn't perfect, but neither is the space that we have, and my portal is just an attempt at quantifying what I'm seeing.

I'm going to create a minimum viable Internet of Things (IoT) version of this portal as well, and use APIs.json to deploy different interpretations of what constitutes a minimum viable API presence. If you have anything you'd like to see in my base template, let me know. If you want to fork and add to, then submit a pull request, even better. I'm just playing around, but also looking to establish a suite of APIs.json driven tools, that help me(and you), better understand the API space.

To help on-board you with my vision, I also added a walk-through for when you land on the site. Something I will be adding to when I have time.

• Details

APIs.json Driven Portal

My goal with this portal is to make it all driven by APIs.json, so I can use as a template for portals, that anyone can fork, and quickly generate an API developer that meets my minimum definition of an APIs.json portal.

The navigation, home page, and almost every other section is pulling its content and references from the master APIs.json, as well as the rest of the 25+ APIs in this index.

There are still a lot of manual details for me, when keeping the APIs.json index up to date, but it is paying off. I have parts of my APIs indexed, like I never had before. This is allowing me to keep better in tune with the details of each API.

• Details

A Little Standardization Around How We Do Internet of Things (IoT) APIs And Developer Portals Could Go a Long Ways

I was dedicating some time to researching APIs in the Internet of things (IoT) space, and stumbled across the Myfox API, serving the Myfox home security products. While the developer portal for the Myfox API doesn't have everything I'd like to see in an IoT developer portal, it is one of the better one's I've seen.

If you think web or mobile app developers suck at providing a simple, and a coherent developer portal and experience, device platform providers are even worse. The Myfox API, has the essential building building blocks, with a simple overview, authentication info, simple Swagger driven API documentation, application management tools, and a clear terms of service for the platform.

Additionally, there is a clear link between the primary Myfox website, the developer portal, and a myfox.me user portal, for device consumers and would-be developers to easily on-board with everything. I haven't fully profiled that Myfox platform, but at first glance it is clean, well laid out, and most importantly the link between the website, API, and user accounts is clear, and easy to navigate.

As I think this through, and after recently finishing a white paper called Building an API-driven Ecosystem for the Internet of Things, for the now defunct GigaOm, I can't help but think the IoT space is going to need to agree on some sort of standard approach for not just managing how they design, deploy, and manage APIs, but also how they deliver developer and user portals. To help you visualize what I mean, consider the number of Internet connected devices any single household will own, all with their own portal, and on-boarding process. #FUN

In short, developers, and end-users will get IoT account fatigue pretty quick. I don't think that we are going to standardize everything across the space, I am not delusional, but I can't help but think that the sharing of some common blueprints, could go a long ways in reducing friction for developers, and device consumers. I'll take my research from the GigaOm white paper and produce a blueprint, that IoT device makers can use, to to hopefully be more successful in deploying their developer portals, platform accounts, and maybe help influence a tiny bit of consistency in how IoT platforms function.

• Details

• << Prev
• Next >>

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.