The UX Of Integration

Recently I've been thinking about UX design for technical integration. How do you build effective digital products for others to integrate with? That is - what does a good API look like?

The persona of the integrator has evolved as the tooling we have to build software has changed.

This isn't merely about whether to use GraphQL or whether to design your API with RESTful standards. Rather, it is about how the human (or more often, the agent) at the other end interacts with your API.

How do you ensure your API products lead to proper moments of joy for your customers and partners in the same way your visual product design does? How do you do this really well with the seismic shift that LLMs and agentic coding have had on the industry?

Are there any evergreen principles that we can continue to apply as the way we build changes?

What Is "Integration UX"

It's easy to think this is simply API documentation. It is not (although that is a large part of it)!

Integration UX refers to a lifecycle. It is a lifecycle that starts in pre-sales, usually with a mixture of commercial, product and engineering stakeholders in the mix. It continues on into post-sales, where contracts have been signed and work has begun.

It is the sum total of the way you interact with a potential customer or partner about your product.

You might argue that because your API is self-serve, there is no lifecycle. I'd argue that there definitely is a lifecycle, and it's the same one. Pre-sales is everything before your customer decides to create an account. Post-sales is everything after that. These lifecycle stages don't require your real-time interactions, but the way your potential customers perceive your product and make their decision will be based largely on the forethought you have given to the user experience.

Across both the white-glove and self-serve lifecycles, the following aspects matter:

• Product Coherence: When a customer first interacts with you (either face to face, or via an artefact), can they match their problems to one of your API products?
• Onboarding Fluidity: What is the minimum path to value for any potential customer? Practically - what needs to be in place to get them to the point of generating an API credential and building?^*
• Integration Ease: Once onboarded, can an engineer easily match their task with the specific API or integration surfaces you offer? Is testing readily available?^**
• Change Management: After the integration work is done, how are changes to the API surface managed? how are you ensuring that your customers are in the loop about what's being changed, and how do you ensure you are making non-destructive changes to your products?^***

^*For institutions and businesses, this requires an incredible amount of thought and care. There are information security, data sovereignty, regulatory, compliance and auditing concerns. This list can be longer or shorter depending on your target customer persona, but thinking about it and making it clear you've thought about it is part of the UX. ↩

^**There are specific "moments of joy" you might want to target here depending on your product. Ideally, you want to be answering questions through your documentation. If an engineer might ask "Is there a way to get a webhook for this data?", set high expectations for yourself to think about those questions and provide answers. Importantly, providing answers =/= building everything customers might ask for. Ultimately you remain the custodian of your API, and must make decisions that "fit". ↩

^***Easier said than done, especially when servicing very large businesses, you must be cognisant of the cost of change for them. A minor refactor for you (changing how 2 endpoints are used together) might result in an incredibly costly change for your customer (requiring internal approvals, InfoSec review and several sprints of delivery and database change requests). Your change management strategies must allow for flexibility for customers in responding to your changes. ↩

Product Coherence

If your company is sufficiently large, you're likely going to have many, many teams working on your API products. It might even be tempting to split off a dedicated API team (or several) whose sole purpose is to define and build customer-facing integration products. If you're really big / successful and providing enterprise software - you're probably investing in FDEs (Forward Deployed Engineers), to work on site, at your customers and deliver software that solves their problems based on your products.

Irrespective of how you organisationally decide to build APIs, it is still critical to have a distilled understanding of what problems your products can solve, and how they can be combined to solve different problems. Even more critical is to have a way of articulating this product<>problem match well to your potential customers. This comes more naturally to anyone in sales or product when what you're pitching has a dashboard or app that you can click through and "show" to your potential customer. Illustrating the value of an integration product is harder, because what you need to show is your thinking (i.e. from the customer's perspective - have you thought about how to integrate with their specific cloud setup, what about their reporting needs?)

The combination of this understanding + the way you communicate it is what I call Product Coherence.

Onboarding Fluidity

Once you've successfully displayed the value of your product relative to the problems your customer is facing, it's likely that you move into onboarding them onto your API. Once again, depending on the size of customer and their complexity, you will need to tailor your approach - ensuring that functional onboarding (getting them access to your tools or platform) is made meaningfully distinct from legal onboarding (signing the contract, getting added to vendor management lists, DD).

This does not mean that you should proceed recklessly - legal onboarding is a key element in ensuring both companies are adequately protected and have a high degree of comfort with moving forward. The separation here is to ensure that the integration team (on the customers side) feel a sense of momentum, and have an understanding of the complexity and size of the integration. This might be a series of scoping / analysis sessions hosted by your project teams with the customer to understand their needs in detail, and plan a "solution architecture".

The guiding metric here for your customers will be "Time To Value" - it should be the same for your internal teams. What is the minimum path to value for this customer, and how are you getting them there?

Integration Ease

At this point, you've figured out the solution architecture collaboratively with your customer, and they're ready to move into integration-mode. This is similarly a high stakes opportunity for your business to prove your product<>problem match.

This step relates to the documentation you have available, SDKs and understanding of modern integration practices.

Getting this right matters for several reasons:

• Engineers on the other side want an easy way to get started on your product, they look for documentation to validate the technical feasibility of integration. At a glance, do your documentation and available artefacts convey what problems your API product solves, and how to use it?
• It helps you ensure that you're building something that can service multiple customers well. This is a hard product<>engineering problem. Where is the line between too generic and tailor-made?

But there are less obvious reasons which are just-as, if not more important:

• It signals externally that you have thought about the customers problems enough to build an API product that "answers the right questions".
• It can, when done right, drive product improvements internally outside of just the API surface. APIs give you the playground to really get your domain modelling and separation of concerns right with a customer hat on.

High Empathy API Design

Forgetting about LLM agents for a brief moment, I think one of the biggest advantages engineers have when building customer-facing API products is the fact that empathy is readily available.

The hard part is tapping into that and really advocating for the fidelity of the product whilst balancing the need to deliver something.

Hard, but not impossible - the guiding principle here should be:

If I was the engineer on the other end of this integration, what would make my life easier?

Agentic UX

For agents - you should now think about the same things as before (how good are your API docs, how does an engineer get API keys, how does your testing or sandbox environment work) with a new perspective.

This perspective comprises (not comprehensive) questions like:

• What coding agent is the engineer integrating with you using?
  • Is it Claude Code, Codex, Open Code? Are you shipping something to simplify development based on what your customers are using to build software?
• Should you ship a skill or CLI alongside your API?
  • That is, can agents interact with your offerings in ways that help speed or simplify development and go-live?
• How coherent is your API surface?
  • Do engineers or agents have to jump around and manage multiple credentials and multiple sets of API documentation to achieve a single task?
    • Is there a domain reason for it to be this way, or is there room for consolidation in lieu of a better user experience?

Further - think about every time you've done an integration. What's your workflow?

• Read the docs
• Start writing up a plan or technical design (maybe you need a new service and a few DB tables)
• Where do you store the API keys? How does rotation work?
• What are the APIs on offer?
• How do I achieve what I need to do based on those APIs? Is anything missing?

Now think about attempting a modern system design task using your current documentation:

Likely doesn't go great - the hosted docs are not readily available for an agent to read, and as such - has to rely on the human to copy-paste. Even worse, there is a non-zero chance that your agent will scrape some of the documentation, but have an incomplete picture of how things work. Inadvertently leading to a bunch of assumptions.

This is easily contrasted to a modern system design task, put up against a company who has made a small investment into an llms.txt file.

The second example doesn't require the company who owns the API docs to be on the bleeding edge. Instead, it required two evergreen (and non-AI) principles:

1. An understanding of how an integrator would work, based on understanding of how contemporary software engineering works.
2. An understanding of possible, emerging solutions to integration problems for the workflow in (1).

Change Management

The integration work is done, and your customer is in production. But your products are not static unchanging artefacts. As your business evolves and grows, your products will ebb-and-flow. This applies to your API products as well. Change management is likely something your customer asked about early in the sales cycle, and you probably had an answer.

But it's important that you think as deeply about change management for your API product as you did for the specific endpoints in your API.

To ensure effective change management for API products, the guiding principle I use is:

How do we ensure fair access to new functionality for customers that want it, whilst minimising breaking changes for customers that don't want it?

In an ideal scenario, with high product coherence - the second group of customers are unlikely to be using the API that is being updated if they do not want the latest functionality.

Unfortunately, that is not always true, and you must plan for it. Additionally - even if every customer using the API needs every new feature, you must still exercise empathy for the engineering effort (and potentially compliance, InfoSec, etc) required from their end to adapt to new changes.

Good API change management is a masterclass in relationship management and documentation quality.

It's a lot, but doing it well is very rewarding

I've edited this and rewritten it many times. But it's because I genuinely enjoy the overlap of product, sales and technology when it comes to API products. Designing them, building them and ultimately getting them into customers hands is interesting, fun and some of the most rewarding work I've done.

If you practice this well enough - you'll be able to delight your customers (and their engineers). If you're technical - this will be a highlight for you and a great chance to build out your commercial instincts.