Perhaps you are undergoing a digital transformation and are looking to formalize your API programme. Or, perhaps you have been put in charge of some existing API that you had no control over. Even with experience combined with a great team, establishing a well-run API programme isn’t easy. There is a lot to do, and it isn’t always easy to know what to focus on next.
This article presents 12 tips for approaching your API programme. These tips can be applied at any stage of your API management journey. Read through each one and identify the actions that would best fit your need.
1. Understand what others are doing. But remember that your organisation is different.
Just because Netflix, Amazon, Twitter, Uber, or Lyft does it, doesn’t mean you should. Under all of those blog posts and conference presentations that sound great lives months and months of meetings, trials, and missteps. I have worked with organisations that have hundreds or thousands of developers, while others may only have a dozen or less developers. Mimicking what a large company does may not fit your small or mid-size organisation.
We can all learn from the lessons of others. But not all decisions these companies made will lead you to the same result. Learn what worked and why – especially the why. Then apply what makes sense for your company.
Finally, don’t be afraid of judgement from others if you don’t choose to go down the most popular or hyped path. Your job is to make choices based on what is right for your company and your customers – not what the “hypesters” assume is the next big thing.
2. Learn the ins-and-outs of the HTTP protocol
There is more to HTTP than you think. From the basics of URLs, HTTP methods, and headers to more advanced topics such as client-side caching and concurrency control – there is a lot to learn about HTTP.
If you are building a web-based API, it is critical to understand how HTTP works. Unfortunately, some APIs are built without this knowledge in hand. Instead, they are built on top of frameworks that hide the details of HTTP. The upside is that the API was built and deployed quickly. The downside is that it was without a proper understanding of HTTP.
Check out our two-part post on “The Power of HTTP REST APIs” (part 1, part 2) to help you get started.
3. Document your API landscape
There is nothing more overwhelming than unknowns. Take the time to find all of the APIs that are in production or in development. This will help you gain a deeper understanding of where data is flowing, who is using your APIs, and how they are being used.
Documentation may start out as a simple list of APIs as you discover them. Eventually, you will need to know a bit more about them. Capture their definitions using a standard such as the OpenAPI Specification. You may need to iterate on this by first identifying the operations available, then expanding your definitions to include all request and response details. You can get started quickly using tools to capture API traffic and reverse-engineer an OpenAPI Specification from it.
4. Understand existing API usage
Do you know which of your APIs are used heavily? Or, which APIs are not used at all? Are there some APIs that need better security than they have today? If you don’t know the answers to these questions, you need to gain understanding and control of your API runtime.
To gain a better understanding of how your APIs are being used, place an API gateway sooner rather than later. This will help you to assess incoming traffic and generate reporting metrics on how each operation is used (and by whom).
Not all applications can be updated to send an API token required by the gateway. In this case, consider temporarily inserting a reverse proxy, such as nginx or Apache, between your apps and API. This will allow you to report on which API operations are being used and how often by analysing the request logs. As you are able to modify existing applications to provide API tokens, shift them over to use the API gateway.
5. Complete a security assessment of your APIs
Once you understand your API landscape and usage better, it is time to determine high-profile or areas that offer sensitive data. Identify operations that expose PII and NPI data. Determine which operations allow anyone to perform tasks without proper authorisation. Then, work to secure them properly.
Securing an API in production without disrupting service may be challenging. In fact, it may require that you work with internal and/or external developers to plan a mitigation strategy faster than expected. But locking down your API is critical to avoid future business-wide issues. Check out our article titled “How Secure is Your API?” for more on the risks of an unsecured API.
6. Establish an API style guide
Consistency for your API consumers – whether they are internal, partners, or public developers – is an important component of a great developer experience. A common design approach, captured as an API style guide, makes integration more intuitive and can reduce troubleshooting and support cost.
Establish an API style guide – even if your current APIs do not conform to it yet. Once established, future changes to APIs in your portfolio will become more consistent and lead to a better developer experience. Our article titled “How and Why to Create an API Style Guide” provides some excellent tips and resources for establishing your API style guide.
7. Implement a DX review process
Once your style guide is in place, begin to establish a DX review process. Similar to a code review, the goal is to encourage learning and drive toward more consistent APIs. The goal of a DX review is to think more like the developer planning to integrate your API – and less as a developer that is implementing it.
A word of caution: a DX review is not an opportunity to tear people down, so provide constructive input while explaining why it is important.
External developers don’t care if you have technical debt. They don’t care if you chose the wrong database. They only care if your API solves their problem and that they can integrate it quickly, and in a manner consistent with your other APIs. The DX review process is designed to catch poor design and documentation before it gets into the hands of these developers.
DX reviews may stand alone, or be part of a larger Center of Excellence (CoE) or Center for Enablement (C4E). Check out some of our recommendations on establishing an API governance process as part of our API style guide” article.
8. Unify your security and access scoping
As you undergo DX reviews, you may realise that you have a fragmented security model. This is common if APIs are gained through an acquisition, or if APIs were designed in isolation to others in your portfolio. As such, it may be difficult to consistently enforce proper security. This needs to be addressed quickly.
Using the initial security review recommended above, create a list of the authorisation scopes your API enforces and who is currently assigned these scopes today. This exercise may surface some critical security holes that need to be addressed ASAP. Or, perhaps it shows that no thought has been placed on API security in the past.
Then start to develop a more forward-thinking picture of what your authorisation scopes and rules should be. Consider both two-legged authorisation for users accessing their data, as well as three-legged authorisation where you may wish to grant limited access on behalf of a user to third-parties. This will provide a gap analysis of where you need to be vs. where you are today. Then work toward closing this gap through a mixture of design improvements and security enforcement.
For additional guidance and insights, refer to our article titled “How Secure is Your API?”.
9. Focus on end-to-end delivery, not layer-by-layer
An API programme is often associated with a larger transformation initiative. This means that architecture and infrastructure modernization may be part of the API effort. This can have a negative impact on getting APIs designed and deployed into production. It may even cause your API initiative to stall.
An anti-pattern to avoid is the idea that you have to design and build out your entire architectural vision, from infrastructure to a full suite of APIs before you can proceed. This will stall any API or transformation initiative.
Instead, deliver a thin slice of your new architecture that solves an end-to-end need. Too often, teams seek to deliver architecture modernization layer-by-layer. This results in a revised infrastructure, databases, and APIs before you ever release one new feature. Nothing will stall a modernization effort more than trying to “get everything right”.
Instead, identify a slice of new or improved functionality. Then implement it. You may have to use some of your existing technology infrastructure to do it. But that is the wonderful thing about APIs: your consumers have no idea what is behind your API. You can migrate these legacy technologies over time while delivering well-designed APIs today.
While you may not be moving to microservices, our article titled “Migrating from a Monolith to APIs and Microservices” will provide guidance for any team seeking to modernize their technology stack.
10. Automate and improve your operations at the same time
Automation and self-service consumption is just as important as having a well-designed API. If you cannot repeatedly deploy a new API without manual steps or opening a service request ticket, then your API programme will struggle. If your API consumers want to use an API you provide, but it requires speaking with a manager or sales to gain access, you have a serious problem.
Increased friction results in obstacles that cause developers to avoid building new APIs. Developers will code to a database, not an API, if it means that they can get things done faster. Build self-service and automation into everything you do.
11. Have a plan for supporting the legacy system
While we may wish that we can start over from scratch, that is rarely the case. Your organisation is running on years of systems that contain data and business rules that need to be migrated. This means you need to plan for how you will support day-to-day operations while modernizing your architecture.
Some organisations may choose to clean-room design their APIs, then map them into existing systems. This allows you to have a “do over” moment by defining the state of the future while allowing your API implementation to deal with the ugliness of today. Sometimes this isn’t possible.
If necessary, give yourself permission to build something new, while supporting something currently in production. This may require some complex data synchronization while you run both systems in parallel. It isn’t always easy, but sometimes the effort required to take this approach is better than the alternative of staying where you are today. Just be sure to weight the risks and identify mitigation strategies that will ensure a smooth transition process.
12. Seek outside input when you need it
Be willing to bounce architecture, infra, and operational questions off those that have seen similar problems inside or outside your organisation/business domain. Sometimes, it can be freeing to hear that you have permission to go outside the lines of what most are saying. Having an outside assessment can help you prioritize your efforts and identify blind spots that may jeopardize your modernization initiatives.
Wrap-up
Running an API programme isn’t easy. There are lots of moving parts, constraints, and legacy baggage. By taking it step-by-step and identifying the critical steps you need to take, you will be able to navigate the process and come out with an amazing API programme that will help your technology and business transformation efforts.
If you’re interested in learning more managing your API programme, be sure to check out our free whitepaper.
