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.07 Sep 2018
This post is part of my ongoing review of the Department of Veteran Affairs (VA) developer portal and API presence, moving on to where I take a closer look at their path to production process, and provide some feedback on how the agency can continue to refine the information they provide to their new developers. Helping map out the on-boarding process for any new developer, ensuring they are fully informed about what it will take to develop an application on top of VA APIs, and move those application(s) from a developer state to a production environment, and actually serving veterans.
Beginning with the VA’s base path to production template on GitHub, then pulling in some elements I found across the other APIs they have published to developer.va.gov, and finishing off with some ideas of my own, I shifted the outline for the path to production to look something like this:
- Background - Keeping the background of the VA API program.
- [API Overview] - Any information relevant to specific API(s).
- Applications - One right now, but eventually several applications, SDK, and samples.
- Documentation - The link, or embedded access to the API documentation, OpenAPI definition, and Postman Collection.
- Authentication - Overview of how to authenticate with VA APIs.
- Development Access - Provide an overview of signing up for development access.
- Developer Review - What is needed to become a developer.
- Individual - Name, email, and phone.
- Business - Name, URL.
- Location - In country, city, and state.
- Application Review - What is needed to have an application(s).
- Terms of Service - In alignment with platform TOS.
- Rate Limits - Aware of the rate limits that are imposed. Production Access - What happens once you have production access. Support & Engagement - Using support, and expected levels of engagement. Service Level Agreement - Platform working to meet an SLA governing engagement. Monthly Review - Providing monthly reviews of access and usage on platform. Annual Audits - Annual audits of access, and usage, with developer and application reviews.
I wanted to keep much of the content that the VA already had up there, but I also wanted to reorganize things a little bit, and make some suggestions for what might be next. Resulting in a path production section that might look a little more like this.
Department of Veteran Affairs (VA) API Path To Production
The Lighthouse program is moving VA towards an Application Programming Interface (API) first driven digital enterprise, which will establish the next generation open management platform for Veterans and accelerate transformation in VA’s core functions, such as Health, Benefits, Burial and Memorials. This platform will be a system for designing, developing, publishing, operating, monitoring, analyzing, iterating and optimizing VA’s API ecosystem. We are in the alpha stage of the project, wherein we provide one API that enables parties external to the VA to submit of VBA forms and supporting documentation via PDF on behalf of Veterans.
[API Specific Overview]
Take a look at the sample code and documentation we have on GitHub at https://github.com/department-of-veterans-affairs/vets-api-clients. We will be developing more starter applications, developing open source SDKs and code samples, while also showcasing the work of other API developers in the near future–check back often.
Spend some time with the documentation for the API(s) you are looking to use. Make sure the VA has the resources you will need to make your application work, before you sign up for a developer account, and submit your application for review.
VA uses token-based authentication. Clients must provide a token with each HTTP request as a header called apiKey. This token is issued by VA. To receive a developer token to access this API in a test environment, please request access.
All new developers must sign up for development access to the VA API platform, providing a minimal amount of information about yourself, business or organization you represent, where you operate in the United States, and the application you will be developing.
You will provide the VA with details about yourself, the business you work for, and your location. Submitting the following information as a GitHub issue, or via email for more privacy:
- Individual Information
- Name - Your name.
- Email - You email address.
- Phone - Your phone number.
- Business Information
- Name - Your business or organizational name.
- Website - Your business or organization website.
- Location Information
- City - The city where you operate.
- State - The state where you operation.
- Country - Acknowledge that you operate within the US.
We will take a look at all your details, then verify you and your business or organization as quickly as possible. Once you hear back from us via email, you will either be declined, or we will send you a Client ID and Secret for access the VA API development environment. When you are ready, you can submit your application for review by the VA team.
You will provide us with details about the application you are developing, helping us understand the type of application you will be providing to veterans. Submitting the following information as a GitHub issue, or via email for more privacy:
- Name - The name of your application.
- Details - Details about your application.
- Terms of Service - Your application is in alignment with ur terms of service.
- Rate Limits - You are aware of the rate limits imposed on your application.
- Working Demo - A working demo of the application will be needed for the review.
- Code Review - A code review will be conducted when application goes to production.
We will take a look at all your details, and contact you about scheduling a code review. Once all questions about your applications are answered, and a code review has been conducted you will be notified letting you know if your application is accepted or not.
Once approved for production access, you will receive an email from the VA API team notifying you of your application’s status. You will receive a new Client ID and Secret for your application for use in production, allowing use the base URL api.vets.gov instead of dev-api.vets.gov, and begin access live data.
Support & Engagement
The VA will be providing support using GitHub issues, and via email. All developers will be required to engage through these channels to be able to actively engage with VA API operations, to be able to maintain access to VA APIs
Service Level Agreement
The VA will be providing a service level agreement for each of the APIs we provide, committing to a certain quality of service, support, and communication around the APIs you will be integrating your applications with.
Each month developers will receive an email from the VA regarding your access and usage. Providing a summary of our engagement. A response is required to maintain an active status as a VA developer, and application. After 90 days of no response, all developer or production application keys will be revoked, until contact is made. Keeping all applications active, with a responsive administrator actively managing things.
Each year developers will receive an email from a VA API audit representative, reviewing your access, usage, and conducting a fresh developer review, as well as review application, access tokens, and end-usage. Ensuring that all applications operating in a production environment continually meet the expected security, privacy, support, and operational standards.
It Is Not Just A Path, But Journey I’m trying to shift the narrative for the path to production into being a more complete picture of the journey. What is expected of the developers, their applications, as well as setting the table of what can be expected of the VA. I don’t expect the VA to bite on all of these suggestions, but I can’t help but put them in there when they are relevant, and I have the opportunity ;-)
Decouple Developer And Application(s) Some of the reasons I separated the developer review from the application review is so that a developer could sign up and immediately get a key to kick the tires and begin developing. When ready, which many will never be, they can submit an application for potential production access. Developers might end up having multiple applications, so if we can decouple them early on, and allow all developers to have a default application in the development environment, but also be able to have multiple applications in a production environment, I feel things will be more scalable.
Not Forgetting The Path After Production I wanted to make sure and put in some sort of process that would help ensure both the VA, and developers are investing in ongoing management of their engagement. Ensuring light monthly reviews of ALL applications using the APIs, and pushing for developers and the VA to stay engaged. While also making sure all developers and applications get annual reviews, preventing what happened with the Cambridge Analytica / Facebook situation, where a malicious application gets access to such a large amount of data, without any regular review. Making sure the VA isn’t forgetting about applications once they are in a production state. Pushing this to be more than just about achieving production status with an application, and also continuing to ensure it is serving end-users, the veterans.
Serving Veterans With Your Application To close, I’d say that calling this a path to production doesn’t do it justice. It should be guide to being able to serve a veteran with your application. Acknowledging that it will take a significant amount of development before your application will be ready, but also that the VA will work to review your developer account, and your application, and ensure that VA APIs, and the applications that depend on them will operate as expected, and always be in service of the veteran. Something that will require a certain level of rigor when it comes to the development, certification, and support of applications across the VA API ecosystem.
As I curate the interesting news from across the API space each week I tag things to put them into different buckets. At the end of each week, I look through each bucket, deciding which area(s) I will be writing about each week. I am always trying to identify patterns and evolve the different areas of my research. One of the areas I'm considering adding as a formal area of API research is when it comes to certification.
I have been seeing the area come up quite a bit, making me think it is something I should be thinking more about, and researching as its own project. This week there were four items thought caught my attention:
- BigML Certifications are Here! - Professional certification on machine learning APIs, from a leading API provider.
- Better Business Bureau yanks Wells Fargo's accreditation - Ok, not quite certification, but a classic representation and story to consider.
- Why cybersecurity certifications suck - A look into why certifications can be better, and applied in a critical area of the online world.
- Eligible Announces SOC2 Certification - Certification than an insurance API provider on their availability, processing integrity, confidentiality, or privacy.
These posts came after another four items from last week, providing, even more, to think about when it comes to APIs and certification:
- A new certification program for Open Source Hardware - I certify that I am truly open source, not that faux open source you see a lot of--we are the real deal!
- Online Dante Certification Program Now Available - Professional certification on audio APIs, from an older school software provider.
- Transform your business; become a Google Certified Professional Data Engineer - Professional certification that you know your stuff when it comes to data, specifically data in the Google ecosystem--data engineers are hot.
- IBM launches Watson application developer certification - Another professional certification for machine learning and artificial intelligence, this time from big blue.
There is a lot going on here when it comes to the concept of certification. I guess the BigML, Dante, and IBM certifications are more of what had in my head entering this post, but thinking about the shady shit that Wells Fargo has been up to, and thoughts on certifying that you are "ethical open source", or "honest open source" is fascinating to ponder as part of the big picture.
Another thing that stands out for me in these certification stories, is that there are two separate certifications for machine learning across the last two week. I can't help but think that there is some sort of purification going on in this ritual, or a sort of validation of the thing behind the certification, meaning that if you certify that professionals know this thing, then the thing, must be a thing. Right? IDK, I just can't help but think more of the motivations behind doing certifications, and the psychology behind how they are perceived (right or wrong)
I'm inches away from adding certification as an official API research area, so I can keep a closer eye on it. I've never been a big certification guy, but I understand why they exist, and why some people invest in them. If I add it as a research area, I'll dive in deeper to map out which API certifications exist out there, and which ones might provide a good model for other API providers to look at, or maybe even what to consider NOT doing when crafting your certification program.
I am coming across more API providers who have carved off specific "skills" derived from their API, and offering up as part of the latest push to acquire new users on Slack or Facebook. Services like Github, Heroku, and Runscope that API providers and developers are putting to work increasingly have bots they employ, extending their API driven solutions to Slack and Facebook.
Alongside having an application gallery, and having an iPaaS solution showcase, maybe it's time to start having a dedicated page to showcase the bot solutions that are built on your API. Of course, these would start with your own bot solutions, but like application galleries, you could have bots that were built within your community as well.
I'm not going to add a dedicated bot showcase page until I've seen at least a handful in the wild, but I like documenting these things as I think of them. It gives me some dates to better understand at which point did certain things in the API universe begin expanding (or not). Also if you are doing a lot of bot development around your API, or maybe your community is, it might be the little nudge you need to be one of the first APIs out there with a dedicated bot showcase page.
I'm going to keep beating the patent API drumbeat, until I bring more awareness to the topic, and shine a light on what is going on. While I will still be my usual self and call out the worst behavior in the space, I am also going to try and be a little more friendlier around my views, and try and help bring more options to the table. This is a serious problem, nobody is talking about, and one that has many dimensions and nuances--if you want my raw stance on API patents, you can read it here.
One area I wanted to try and cover, in response to my friends trying to convince me their aren't bad people, in having patents. I know you aren't, and it isn't my goal to make you look bad in this, it is only to shine light on the entire process, how broken it is, and call out the worst offenders. If you truly believe in patents, protecting the work you've done, and that your intentions are good, share your patent portfolio with the world, and showcase it like you do the other aspects of the work you do. You will craft a press release about everything else you do, do the same for your patents.
I do not think patents are bad. I think ill-conceived patent ideas, that haven't been properly vetted by the under resourced USPTO, that are used in back door dealings as leverage, and litigated in a court of law are bad. I'll take your word that your patents are good, and you aren't operating in any of these areas, if you are public, transparent, and openly proud of them, as you state in private conversations.
Part of the purpose of my research is to encourage good behavior in the sector, by highlight the common building blocks of the space. I think I will add a patent portfolio building to my research. While I have ZERO examples to highlight, I encourage API companies to do this, and would love to highlight in a positive way, any company that is straight up enough to showcase their patents. If you are proud of your API patents, and do not have bad intentions in having them, please publish your portfolio, show case them as you would anything else you are doing--help bring API patents out of the shadows.
Time Tracking API platform Harvest has embraced Github as part of their API ecosystem. I'm always on the hunt for examples of API providers using Github, so I figured I'd showcase Harvest's creative use of the social coding platform.
Starting with their documentation, the Harvest team has moved the API documentation to a Github repository, allowing developers to "watch" the API, get updates when changes are made, asks questions or even contribute to the API docs by submitting a pull request.
Harvest is also using the wiki portion of their Github repo for a developer application gallery they are calling Community Creations and Hacks, where they showcase innovative uses of the Harvest API--currently displaying 20 integrations by Harvest users.
I'm currently tracking on 11 separate uses of Github for API management, and always on the hunt for new ways to use Github to support API ecosystems. Nice move Harvest!
I stumbled across the Twitter Counter API in my monitoring for the API Stack this morning. The Twitter Counter API allows you to retrieve key metrics on any Twitter account like username, url and avatar. All data you can get via the Twitter API, but with Twitter Counter API you get additional information like account growth statistics and ranking, that Twitter doesn't provide at all.
I find it fascinating that someone can build an API to augment an existing API, which is why I keep talking about it, I guess :) We are seeing a more standardized version of this with API aggregation providers like Singly and Adigami, where they not only aggregate APIs from a variety of sources, they also build entirely new APIs based the added value that is created after they are brought together.
Thinking about if further, it would be cool if you could submit your API to be listed in your parent API providers API area. Think of APIhub and Mashape, but every API area would have its own 3rd API marketplace. API providers often allow 3rd party developers to submit code libraries and samples to be listed as resources, as well as applications for listing in an application showcase. So it makes sense to potetially allow for your developers to submit APIs for validation and publishing into a designated area.
Poster boy for how to properly run your API ecosystem properly, Twilio, recently updated their DOer Gallery to highlight developers in the Twilio ecosystem that build cool stuff on the popular voice and SMS API.
Twilio has the best record I’ve seen of any API, when it comes to showcasing and being loved by their developer community, and I'm sure the DOer Gallery plays an important role in that.
The Twilio DOer Gallery has the following features:
- Personal Details
- Short Bio
- Other Profiles
Devloper Galleries like Twilios might not be for every API platform. But if you have a passionate base of developers you might want to consider giving them their own profile and a gallery where they can not just discover and interact with each other, it can let other companies find potential developers to execute projects via your API.
A Developer Gallery can be a great way to give your API developers some love and attention. Twilio even features developers from their DOer Gallery on their blog in a "DOer of the Month".
Would showcasing your “API DOers” benefit your API community?
Factual has launch a new application gallery to showcase the diverse number of applications built using data provided by Factual.
You can search for apps, browse by category, and filter by open source, paid or free apps. Looks like there are about 18 apps in the directory currently ranging from augmented reality to daily deals.
The Factual App Gallery isn’t a particularly unique launch, we are seeing app showcases popup within many APIs, but it shows that Factual is gaining steam, and I think it shows the appetite for building apps around datasets is growing.
- 1st prize - Makerbot Thing-O-Matic 3D Printer
- 2nd prize - 1TB USB hard drive enclosed in a vintage nintendo game (Zelda, Metroid, etc)
- 3rd prize - Set of BuckyBalls magnetic building spheres
- NewIn - This application shows new members joining LinkedIn from around the world.
- ChromeIn - Integrate LinkedIn directly into Google Chrome. Easy access to your LinkedIn updates, anytime.
- Signal - Signal is aimed at making it easy for all professionals to glean the most relevant insights from the never-ending stream of status updates and news. An API Labs is a great way to showcase experimental and innovative projects that utilize your API.
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.