As one of my clients is preparing to move their API from deployment to management, I'm helping them think through what is necessary to make sure their API is ready for use by a wider, more public group of developers. Ideally, I am brought into the discussion earlier on in the lifecycle, to influence design and deployment decisions, but I'm happy to be included at any time during the process. This is a generalized, and anonymized version of what I'm proposing to my client, to help make sure their API is ready for prime time--I just wanted to share with you a little of what goes on behind the scenes at API Evangelist, even when my clients aren't quite ready to talk publicly.
External Developer Number One
The first place I can help with the release of your API is when it comes to being the first external developer and fresh pair of eyes on your API. I can help with signing up, and actually making calls against every API, to make sure things are coherent and stable before putting in the hands of 3rd party developers at a hackathon, amongst partners, or the general public. This is a pre-requisite for me when it comes to writing a story on any API or doing additional consulting work, as it puts me in tune with what an API actual does, or doesn't do. The process will help provide you with a new perspective on the project after you have put so much work into the platform--in my case, it is a fresh pair of eyes that have on-boarded with 1000s of APIs.
Crafting Your API Developer Portal
Your operations will need a single place to go to engage with everything API. I always recommend deploying API portals using Github Pages, because it becomes the first are to engage with developers on Github, as part of your overall API efforts. Github is the easiest way to design, develop, deploy, and manage the API portal for your API efforts. I suggest focusing on all of the essential building blocks that any API operations should possess:
- Landing Page
- Tag Line - A short tagline describing what is possible using your API.
- Description - A quick description (single paragraph) about what is available.
- On-boarding
- Signup Process - A link to the sign-up process for getting involved (OpenID).
- Getting Started - A simple description, and numbered list of what it takes to get started.
- Authentication Overview - A page dedicated to how authentication works.
- FAQ - A listing of frequently asked questions broken down into categories, for easy browsing.
- Integration
- Documentation - Interactive documentation generated by the swagger / OpenAPI definition.
- Code - Conde sample, or software development kits for developers to put to work.
- Postman Collection - A Postman Collection + Button for loading up APIs into Postman client.
- Support
- Github - Set up Github account, establish profile, and setup portal as the first point of support.
- Twitter - Set up a Twitter account, establish a presence, and make know open for business.
- Email - Establish a single, shared email account that ca provide support for all developers.
- Communications
- Blog - Establish a blog using Jekyll (easy with Github Pages), and begin telling stories of the platform.
- Twitter - Get the Twitter account in sync with communication, as well as support efforts.
- Updates
- Roadmap - Using Github issues, establish a label, and rhythm for sharing out the platform roadmap.
- Issues - Using Github issues, establish a label, and rhythm for sharing out current issues with the platform.
- Change Log - Using Github issues, establish a label and rhythm for sharing out changes made to the platform.
- Status - Publish a monitoring and status page keeping users in tune with the platform stability and availability.
- Legal
- Terms of Service - Establish the terms of service for your platform.
- Privacy Policy - Establish the privacy policy for your platform.
All of these building blocks have been aggregated from across thousands of APIs, and are something ALL successful API providers possess. I recommend starting here. You will need this as a baseline to get up and running with developers, whether generally on the web or through specific hackathons and your private engagements. Being developer number one, and helping craft, deploy, and polish the resources available via a coherent developer portal are what I bring to the table, and willing to set aside time to help you make happen.
Additionally, I'm happy to set into motion some other discussions regarding pushing forward your API operations:
- Discovery - Establish a base discovery plan for the portal, including SEO, APIs.json development
- Validation - Validate each API endpoint, and establish JSON assertions as part of the OpenAPI & testing.
- Testing - Establish a testing strategy for not just monitoring all API endpoints, but make sure they return valid data.
- Security - Think about security beyond just identity and API keys, and begin scanning API endpoints, and looking for vulnerabilities.
- Embeddable - Pull together a strategy for embeddable tooling including buttons, badges, and widgets.
- Webhooks - Consider how to develop a webhook strategy allowing information to be pushed out to developers, reducing calls to APIs.
- iPaaS - Think through how to develop an iPaaS strategy to allow for integration with platforms like Zapier, empowering developers and non-developers alike.
This is how I am helping companies make sure their APIs are ready for prime time. I regularly encounter many teams who have great APIs but have been too close to the ovens baking the bread, and find it difficult to go from development to management in a coherent way. I have on-boarded and hacked on thousands of APIs. I have been doing this for over a decade, and exclusively as a full-time job for the last seven years. I am your ideal first developer and can save you significant amounts of time when it comes to crafting and deploying your API portal.
As a one person operation, I don't have the time to do this for every company that approaches me, but I'm happy to engage with almost everyone who reaches out, to understand how I can best help. Who knows, I might help prevent you from making some pretty common mistakes, and I am happy to be a safer, early beta user of your APIs--one tha will give you the feedback you are looking for.
