When it comes to building tech initiatives, we often say that they should be treated as products in order for them to succeed. Treating your internal APIs as a product means that you’re not just thinking about the utilitarian nature of your systems — you’re thinking about internal users as consumers, and thereby prioritizing the UI, UX, and overall developer experience.

Accordingly, one of the most helpful things you can do to bring this mindset to bear is to create a go-to-market checklist for your internal APIs. Your market might be your internal teams, but they are consumers just like any other external user — and building for their experience and intent is the best way to facilitate high quality and directional alignment.

Whereas externally facing public APIs are often part of larger platforms or monetized as products, internal APIs face developers who are internal to an enterprise. That said, they warrant their own forethought and product-thinking. Below, we’re going to give you a step-by-step checklist that you can deploy for your internal APIs. Going through these steps will ensure your release is as good as it can be — regardless of how internally facing it is.

1. Define Ownership and Outcomes

Fundamentally, internal APIs tend to fail when everyone owns them — because if everyone owns a bit of it, then nobody owns any of it. When releasing your API internally, you need to short-circuit this issue by stating clear lines of ownership, as well as what outcomes you will measure for long-term health and maintenance.

The first part of that process is relatively easy. You need to make sure that your internal API has a clear product owner and very clear lines of ownership, consultation, and responsibility. You should ultimately have a singular voice that owns the health of the overall project, but you should also lay out lines of escalation should issues arise around security, accessibility, and so forth.

The second part is a bit trickier. It’s really easy to treat internal APIs like a “good enough” exercise — but if we want to really treat it as the product it is, we need to identify success and failure metrics. Form a clear understanding of the defined value proposition — that is, who uses it, and why. From there, you can start to define success metrics — such as adoption by internal consumers, component reuse in other APIs, service uptime and availability, and even net promoter score (NPS) for developer utilization.

Alongside this, you need to set an understanding of what failure looks like, as well as create feedback loops with API consumers that will allow you to address faults or issues in the long term. This will result in a better product, a happier user base, and a better adoption, development, and sunsetting plan.

2. Standardize Your Design (and Documentation)

Now that you have some solid metrics around what is a success and failure for this API, you need to go through the effort to standardize both your API design and its documentation. Reuse of internal APIs only happens when consumption is easy and aligned with standards — and while you don’t need to completely rebuild your API before release, it’s a good step to make sure that you generally align with the implicit specification of the organization.

This can be different for every organization, but there are some general topics that you should hit across any product release internally.

One area is alignment on company-wide payload and naming conventions. For example, suppose your API has users in the Product space and the Product team is separated into three groups: State, Release, and Review. In this case, your API nomenclature should reflect that. For instance, instead of having api/product as your endpoint, having api/product/state, api/product/release, and api/product/review will help organize requests and functionality in a way that reflects the internal org.

A good example of how an enterprise can deploy API standards at scale can be seen with Google’s AIP process, where a proposal is filtered, reviewed, justified, and implemented through a static alignment process. Keeping within this same concept, you really need to ensure your documentation is kept up to date, but is also aligned to release and update patterns across the company. There’s no need to update your documentation on a schedule that’s opposite your typical release schedule — in fact, you are more likely to get adoption traction if your documentation and versioning are aligned to general release standards and schedules for the rest of your products.

Finally, you need to ensure you’re adopting the standard processes that go into external API releases. This means offering common API description formats (OpenAPI, AsyncAPI, and so on), providing standard error primitives, and creating SDKs for major languages in current use in the organization.

3. Make Identity and Access Control Boring

A significant consideration at this stage is how you handle your identity and access control. Just because an API is internal, that doesn’t mean that it’s secure — and privilege escalation is one of the most common vectors for data breaches arising from internal APIs.

To mitigate this, you need to make identity and access management boring — which means figuring out your flow and establishing clear controls. Firstly, you should determine where your identity authority rests — and once you’ve figured this out, you need to specify your scopes and claims to make sure that each resource or domain is properly secured.

Next, you need to plan out how granular your access control and policies are going to be. Internal APIs are often plagued by “good enough” solutions or shared keys, so you want to make sure that your access control is as low-friction as possible. While making sure your system is low friction, you also need to make sure that it’s enforcing the principle of least privilege. This is a delicate balancing act, and it’ll come down to both your internal culture as well as the requirements of the tool itself as to how you develop and implement your strategy.

4. Plan for Security, Compliance, and Governance

Having an internal API necessarily moves a lot of what might be external systems internally. In a typical externally released API, organizations that adopt the system will have their own security, their own compliance, and their own governance processes — but since you are launching this internally, you need to actually build those systems yourself to align internal resources and processes.

What this means will be different for each organization, but some common areas to consider include:

• The specific threat modeling for each API domain, including internal threats and privilege escalations.
• Data classification and masking rules to ensure that internal data is not allowed to “skip” typical security filters before moving to external processes.
• Security reviews and audits to ensure that internal utilization and data processing do not sidestep other standard security processes and procedures.
• Automated scanning to ensure that vulnerabilities are prevented, addressing dependency drift, out-of-spec API use, and other typical issues arising from organizational drift.
• Implementing zero trust systems — just because an internal API is internal does not mean that it is not prone to the same risks or that it will forever be internal-only.

5. Consider Discoverability

Without discoverability, internal APIs may fail to be readily found or utilized, or may be accidentally duplicated. Yet, discoverability is a complicated objective for a variety of reasons. In a typical go-to-market strategy, your discoverability would be quite flexible, as you would be targeting your specific API user and positioning the product for them. For this, you must balance discoverability with an internal marketing approach.

Accordingly, a lot of the work you will do here will be about ensuring low friction as well as alignment with team culture and expectations. Setting up an internal API catalog or developer portal will help with the friction part. Still, you also need to ensure ownership around maintenance to ensure the APIs are as much an internal product as they are one centered around user experience.

6. Govern Democratically

You should also consider how internal contributions will be handled. It can be tempting — and frustratingly common — to consider an internal tool the product of a single team that is then owned, developed, and versioned by that team. However, other teams might have their own functionality or use cases that can expand the tool and generate additional buy-in. You want to facilitate this more collaborative development process while still managing the expectations and ownership models of the corporate structure. So, you need to properly plan how you will handle PRs and govern additions ahead of time, and then clearly express that to all.

One good example of such a system in practice is Atlassian’s approach to API governance. Atlassian developed an internal API Governance Framework, which allows for an automated, democratic, and intelligent way to work with developers on their governance and integration systems. By connecting directly with potential users and developers while providing a structured method for implementation, integration, and collective development, Atlassian is able to collaborate on APIs while retaining standards and control.

7. Establish Measurement for Adoption and Reuse

Finally, you need to figure out how you are going to measure adoption and reuse of the internal API. External APIs can often abstract away this process somewhat because your API is either used or it is not. Often, you are either making money or you are not. On an internal API basis, this is not a helpful metric — and so you need to create something else to measure success.

There are a handful of ways you can do this. In terms of general utilization, you can target usage tracking, measuring specific API calls, the number of connected consumers, production dependency count, and other metrics to show how widespread and used your system is. This will only get direct use, however, so you’ll want to also build in additional tracking around how many components are reused in other systems and how widely integrated the API services are to merge the success or utilization of derivative products into the core API success metrics.

There is also quite a lot you can do through direct measurement and action of consumers. Employing developer sentiment surveys will help you understand how your API is measured against preference or use case, and can also help you understand general sentiment for user experience and friction. Engaging in regular sentiment reviews as well as surveys that ask about continued development — or desired product iteration — can also help improve the internal API product in a way that simple use metrics cannot.

The Final Word: An Internal API Is Still an API

Ultimately, this checklist should cement a singular concept in your mind — internal APIs are still APIs, and as such, they require a more product-oriented mindset than most internal tools. You need to ultimately treat the internal API as a product, and consider the users — your colleagues and coworkers — as actual users. This means investing heavily in user experience, developer experience, and overall quality of life to ensure product adoption as well as positive sentiment.

If you can treat your internal API as a valid product with actual consumers, following this checklist to ensure high quality, then you will be on a path of high adoption, positive sentiment, and, ultimately, more collaborative development.