API thought leadership typically focuses on external interaction. This makes sense for API products, and most guidance in the API space is general enough to cater to both internal and external paradigms. Even with more specific advice, the assumption is that most consumers hit an API through an external endpoint, focusing optimization on that friction point.

Because of these assumptions, things like the famous Bezos Mandate have become de facto guidance for the entire API space, while only reflecting part of the picture. What happens when your consumers are strictly only internal users? What happens when the consumption pattern is entirely internal?

Today we’re going to address internal API-first approaches and give some purpose-built advice for internally-focused APIs.

Treat Internal APIs With Care

Firstly, we should note here that some things obviously don’t change between internal and external API types. Developer experience is always going to be incredibly important, regardless of the source of that user. The flow of engagement should be clear, easy to understand, and easy to interact with. Documentation should be substantial and meaningful, avoiding any sort of flow that forces users to investigate common problems that are easily solved. In essence, no matter what kind of user is being served, they should be considered the “customer” and supported as such.

Of course, the same security considerations exist regardless of the source of the user. Adequate authorization and authentication schemes are required to ensure that systems are secure from unwanted utilization — this requirement does not go away simply because the user is internal. Moreso, it is essential to secure such internal systems, where the user is more likely to be granted higher authorization (more on this in a moment).

Finally, the core experience must be supported as a product for utilization regardless of who uses it. There is an unfortunate line of thinking among some product developers who consider an internal user as different from an external — in other words, give the “nice product” to the external user, and depend on the internal user’s knowledge to make up for development time on interior solutions. The reality is that an internal user is just as important and should be granted just as polished and effective a solution and implementation as the external user.

What Makes an Internal API Different?

That being said, external API users are notably different from internal ones. Internal users are typically a different kind of user. They may have more specific and higher-level needs of the API. Whereas an external user is often coming to an API product for a single function or purpose, and usually through a frontend integrator, internal users are often looking to engage with the API in its totality to accomplish more complex transformations and interactions.

Additionally, an internal API user may have increased authorization that requires more granular division, whereas external APIs typically separate authorization roughly around different levels of users. Internal users generally are already owners of elevated access, more accurately divided by the functional groups they can utilize. It is less accurate to refer to an internal user as belonging to a group such as “admins”, and more accurate to refer to them as belonging to the “content deletion group”.

Tips for Internal APIs

Internal APIs come with a particular set of approaches and suggestions that can make them more effective, scalable, extensible, and usable. Keep in mind that any amount of tips and guidelines cannot serve as a replacement for a cohesive API plan — just because the product is internal does not mean it should not be treated as a product in and of itself. That said, these tips will go a long way towards improving the average developer user’s internal experience.

Utilize Internal Style Guides

API style guides are perhaps one of the best tools that an organization can have for internal API development (let alone API development in general — a topic we’ve discussed previously here). An API style guide is a set of guidelines and principles that help developers craft their API around functions, requirements, business purpose, and overall style. This guide broadly falls on a line between two polar opposites –—authoritarian and autonomous.

Authoritarian

An authoritative style guide is strict and dictates a wide variety of functions, design ethos, approaches, and more. This style of guidance can be highly effective for internal APIs that touch regulated data or essential internal systems — for instance, payment processors may have to adhere to strict payment and financial regulations. As such, internal APIs built around this data interaction may need strict guidelines to ensure compliance.

An authoritarian stance also helps organizations in which the API is tightly-coupled to a specific design paradigm. B2B partner scenarios may require tight-coupling. In such cases, an internal API may want to enforce this coupling internally as well, providing a unified and sensible experience between both the internal API and the external product.

Autonomous

On the other side of this spectrum is the more laissez-faire autonomous guideline. This is far more general, and is best suited for loosely-coupled experiences. In this approach, guidelines are general-purpose suggestions, rather than demanding adherence to a strict set of rules.

An autonomous is better suited for internal APIs that are but a set of functions, rather than a cohesive and unified offering. Many organizations utilize internal API development as product incubation, and tests for new forms and functions. In this case, a more autonomous development style guide is important, as it allows for the widest breadth of options and freedom. This is also important when considering internal APIs for individual functional units — it may be true that an internal operations API does not need to conform to stylistic constraints built for media fetching APIs, and as such, a broader set of guidelines could be far more appropriate.

Implement Data Record Systems

Internal APIs often touch data that is not available to external users — in part, that is why they must be kept internal. It’s easy to think that internal users touching internal resources are trustworthy and thus do not require the same heuristic tracking and data security as public APIs. The reality is that API owners must secure all exposed data, regardless of the caller.

As such, implementing a data record system is vital. API owners should record each transformation, each service, each data manipulation, etc., to ensure data integrity. This is linked to the idea of API versioning — that is, having an apparent system that states what version the API or data source is and a documented system for lifecycle management.

As equally important as the process of integrity is the fact that these data systems should serve as a singular source of truth. While this is important in all versioning approaches, it is paramount in terms of data record integrity that there should only be one source of truth for all data records. Notably, this source of truth, if used for records that can be manipulated through external systems as well as internal ones, should synchronize both interactions to ensure total data integrity.

Keep Traffic Internal

As we mentioned above, internal APIs can, at times, interact with data and resources that are also transformable through external systems. It is tempting to consider internal and external APIs as two sides of the same coin and treat them as such. The reality is that internal APIs and external APIs are divided by a solid wall, and should be considered isolated halves of the same whole. Internal traffic is distinct from external traffic.

Take, for example, a customer management system that utilizes an external API to interact with customers but an internal one to process payments. It may be tempting to simply build a single API that has credential locks to critical functions. In this case, what you actually have created is a hybrid API — an API divided between two use cases.

In reality, if utilizing an internal API, you should expect a shim API to transform, translate, and restrict data transfer between the internal and external — especially if any payment data or other protected data is being handled. An internal API can certainly touch the same data an external API would, but this process should be the hand-off of data from one domain to another, not the simple rebranding of the same data set in a different context.

Avoid routing data outside of the internal API unless it is absolutely necessary. To that point, avoid sending external data internal unless required as well. Data that is external should be necessarily handled externally, and the same is true of internal data.

Limit Access by Functional Group, Not User Rank

While this is somewhat of a general security guideline, it’s stated here as failure to do this internally could be far more harmful than externally. When setting up access to a resource, call, or function, ensure that the access is limited by the functional group — that is, if a user’s role is to provide customer support, restrict their access to customer support functions.

Limiting access is especially important for internal APIs, as internal APIs are more likely to have system admins, financial entities, and others working internally. A financial auditing team may request heightened access. It may seem prudent to provide them this access, but what if that team is actually a security team conducting security testing? What if a partnered vendor on the internal API who may need to access limited customer access is given full customer access, and then they are breached?

These sorts of concerns are already issues with external APIs, but internal APIs are necessarily going to touch more regulated and private data, where the potential damage is far higher. This may even be required given tightly coupled API security practices and policies when aligned to business or system practices and procedures.

Rotational access (that is, limiting heightened access to a single role or system at a time), heuristic tracking (monitoring the internal API to track out-of-the-ordinary behaviors), and other methods used to ensure business operations are secure can also reflect into your internal API practices. This may create expectations for how access is limited.

Document, Educate, and Support

Documentation is essential regardless of whether or not an API is internal or external. It’s hard to think of your colleagues who you’ve worked next to for months developing an API as uninformed users, but the reality is that even your most ardent colleagues are not perfect. These people are not going to remember the subtle minutia of every form and function. Even though they are an internal user, they may require the same documentation, education, and support as an external developer.

Documentation, education, and support should mirror that of your externalized resources, but to the level of complexity and coverage required by the internal user base. If an admin needs to know administrative functions, this should be comprehensively covered, with a simple link, email, or other resource they can follow up on for more information.

At the end of the day, it’s tough to consider internal users as non-comprehensively understanding mega-users; nevertheless, this support must be adequately and comprehensively provided.

Conclusion

Though they are often conflated with one another, internal APIs are different from external APIs. The reality is that the expectations, demands, and needs of an internal API require a nuanced approach, or at the very least a reconsideration of assumptions. With the proper mindset, development approach, and internal API-first considerations, an internal API can be highly effective and secure.

What do you think of this advice? Are we off-base? Let us know in the comments below!