5-tips-for-starting-your-API-journey

5 Tips for Starting Your Public API Journey

5 Tips for Starting Your API Journey and Releasing a Public APINew public APIs hit the market all the time. Behind these APIs sit a myriad of different providers; individual developers, startups and established businesses who have all concluded that they need a public API program in order to better serve their audience. Doubtless these new API providers will all have different ideas on starting a public API program, the implications for their business, and what their future plans for expanding or enhancing their API entail. In this post we’ve drawn together 5 tips for starting a public API program, with some advice on what to consider when you go from zero to a production API deployment.

Starting a public API program is a massive topic and we’re only scratching the surface in this post. For the sake of brevity we are also ignoring the fact that organizations are also being compelled to create public API programs through regulation such as Payments Services Directive 2. Some of these tips still apply of course.

Review these points to see if you really need an API1. Clarify Your Needs

First and foremost, before doing a scrap of work your first task is to clarify that your organization actually needs a public API program. This is hugely subjective given the spectrum of organizations interested in APIs, from one-man-bands to huge multinational corporations, and is compounded by the varying motivations behind constructing an API. As soon as your API program is considered necessary stop and ask yourself these questions:

  • Would my product/platform benefit from having an API?: There are many compelling reasons to start an API program: enabling choice for customers in how they consume your products, extending the reach of your product to your customer’s customers, and enabling new business channels with partners, to name but a few. Regardless of the hype surrounding APIs, if you can objectively say yes to any of these reasons then starting an API program is worthy of investigation;
  • Are my customers asking me to deliver my product/platform to them differently (especially via an API)?: Much of the clamor for delivering an API will come from the userbase. Again there will be a huge amount of subjectivity and self-interest in their reasons for asking for one: Some will ask purely because they’ve heard the term and noted that some of your competitors offer them; while others will have a genuine need, such as the desire to integrate your product with other applications they use. Integrating your product stack into their workflows is disconnected and manually intensive, so integrating via an API is hugely advantageous. Both of these are compelling reasons to act: If you don’t have an API but your competitors do, what’s to stop your customer from doing business with them?
  • Do I understand the effect that introducing an API will have on my business (both good and bad)?: It’s possible that your organization could be profoundly affected by introducing an API. For example, an API may change the operating model of your business from daytime hours only to a 24×7 operation, or may be so transformative as to turn your business into an ‘Infrastructure-as-a-Service’ model. One needs only to look at Amazon to see how disruptive the effect of creating a public API program could be on your business.

If you can answer these three questions positively then starting an API program is definitely in the interests of your organization. Your task now is to get wholesale buy in from stakeholders in the business.

roadsign enterprise connectivity releasing public api2. Get Buy In (From Everyone)

As we started to discuss in tip #1, you should be clear that unless your API is the main channel for selling the product you are building, starting an API program could fundamentally change the way your business operates. For example:

  • Your API could disintermediate parts of your own business (for example, if you rely heavily on direct sales). Is the leadership team ready for the implications this could have on the workforce?
  • If providing an API drives volume, can your business cope with that extra volume without change?
  • Do you have the team and resources to build adaptive code and scale your developer relations so that the API is treated as a full-scale product?
  • Do your backend systems that will be exposed by the API have the means to support an abstracted security model or identity provider, and are you aware of what doing so will mean for the threat of cyber attacks and risk management?

In order to be successful in starting your API program you need every member of the team to understand that you are effectively extending your internal systems outwards. The impact will have both a technical and business focus, so it’s important to communicate in a way each stakeholder understands. Fostering a culture of security, and adopting an API mindset throughout an entire organization is vital for success.

3. Aim for a Public MVP

iterative development when releasing public apiWith the need established and the team on board, you should have a clear picture of why you are building a public API and who needs to be involved. You can now create a vision of what your API will deliver in the form of a minimum viable product (MVP), delivered to the market as an alpha or beta. This MVP will allow you to get your API in front of potential API consumers as quickly as possible and allow you to start collecting feedback. The MVP are steps 1 and 2 of a 3-step process:

  1. Initial build out of the MVP with internal private testing only;
  2. Offering the MVP to a select audience of existing customers or partners who have the potential to become consumers of your API;
  3. Migrating the MVP to a production-ready version of the API, ready for general availability.

In order to get the most value in your goal of offering a public API the MVP should be comprised of a number of things:

  • A publicly available endpoint or simple sandbox that can be used by potential API consumers to trial your products, with enrollment either by invitation or with a set of test credentials known only to your target audience;
  • An API description in a specification format of your choice (OpenAPI, API Blueprint, RAML, etc.);
  • Documentation, possibly in the form of a cookbook that describes how to implement an application that consumes your API;
Check out our post on decreasing onboarding time for your API consumers for a view on what should be included in your cookbook or tutorial
  • A well-formed security model so that potential API consumers will understand the implications of integrating with your API;
  • Establish a means to support API consumers who are trialling the API through a medium of your choice: Twitter, Slack, email or whatever makes the most sense for your organization;
  • Analyze how those trialling your API use it in an effort to understand if there are any potential design flaws;
  • A high-level terms of use so API consumers are aware of the expectations surrounding the usage of your API: If there are stipulations that may discourage certain consumers it’s probably better that they aren’t part of your audience when you introduce the MVP.

With the MVP available to potential API consumers you are at liberty to take advantage of the next tip: Acting on the feedback.

4. Act on Feedback

accepting user feedback releasing public apiWith the MVP in the market and channels of communication back to the API team in place, you have a unique opportunity to elicit and act on feedback before a public release. Your API will of course continue to evolve but with this early feedback you are at liberty to perform elements of wholesale reengineering. Such actions might include one or more of the following:

  • Revisit the design of the API and ensure it’s updated to reflect any feedback on usability;
  • Ensure you listen to reasonable customer demands for different encoding types: The majority of new APIs use JSON as their encoding of choice, but if it makes sense to provide the data as XML because the majority of your potential API consumers prefer XML for legacy reasons you should consider it;
  • Ensure the rate limits and throttling you introduced with your MVP can realistically be sustained when higher usage is applied;
  • Tweak your conditions of use to ensure you address your target audience correctly, giving your API consumers terms they are happy to commit to, but also allowing business to sustain as your API grows.

By taking these actions you will be in a much better place to release version 1.0 of your API. However, you’ve got version 1.1, 1.2 or even version 2.0 to think of; another point in our arsenal of tips for building a public API program is to future proof your organization by building an API practice that can support future releases.

For a view of how APIs continually evolve check out our post Your API is Never Fully Released

Create a Practice of Excellence When Planning a Public API Release5. Build your Practice

Building an API practice is similar to creating a center of excellence or community of practice as in any other technological or architectural discipline. However, the API practice should be geared towards a method for developing APIs that ensures you can go from zero to production with a known series of standards and methodologies and the minimum amount of fuss. Some tenets of this practice are:

  • Expressing a clear vision of the API and the roadmap of features, releases and enhancements that will help your business meet that vision;
  • Create an architecture and development framework that support productivity and will allow you to iterate rapidly on the items in your roadmap: Using practices like API-first design with a API description format that best suits your needs and possibly a tool like Stoplight to help model your APIs will give you a better chance of delivering new APIs and API versions with the greatest efficiency;
  • Create an internal style guide for your API developers that can support your productivity efforts by making API designs consistent;
  • Make the most of your infrastructure and DevOps tools: The options for choosing an approach to API development are vast and include different models; SaaS-based API lifecycle management tools, web application frameworks and PaaS, containers, and so on. However, whichever option is right for your organization will ensure that you leverage the value of continuous integration and continuous delivery to really help accelerate delivery;
For further information on DevOps tools in an API context check out our eBook.
  • Keep your internal stakeholders informed and involved: There may be aspects of your roadmap that draw new areas of the business under the API banner and therefore affect different operational or support teams. Having clear lines of communication and engagement with these teams is vital for the continued success of your API;
  • Communicate externally: Your MVP has been a success and you’ve started to engage with your target audience, but there’s a momentum that needs to maintained. Ensure you are communicating your goals with this audience in a way that that casts the net wider; publish articles and blogs extolling the value of your API in the context of the industry you operate in and ensure you address discoverability techniques like Search Engine Optimization and directory bookmarking for your documentation pages so that potential customers can easily find your API.

Final Thoughts

The tips we’ve drawn together in this post should help shape your thinking if you are considering starting a public API program. However, every business or organization’s circumstances and motivations are unique, so most importantly trust your gut instincts. APIs are a great method for taking products to market, so trust your own judgement and use what advice you can from this post to help make your public API program a reality.