What does BYO-AI mean for your company’s API strategy?
This article goes into the obvious, and subtle, changes that need to happen to support customers bringing their own AI.
All Features Need To Be Fully API Accessible
AI can only interact with publicly facing endpoints. Any feature that isn’t publicly facing, or is only accessible through the UI, isn’t accessible to your customer’s AI.
Embracing your customer’s use of AI means making all of your features publicly available. Now is time to reevaluate past decisions about excluding features for performance, scalability, security, pricing, and other reasons.
Customers come to you with problems and AI opens up entirely new avenues for solutions; but only if you let AI into your API.
All Features Need To Be Documented
AI is going to learn about your API by reading the docs, reading the example code, and then reading StackOverflow.
If you want AI to do a good job writing code against your API, you need to do a good job telling it how. Undocumented endpoints, missing parameters, and bad code examples make that harder.
Outdated docs and libraries need to be scrubbed from the internet. It is very much like hiring a reputation company to ensure that what AI sees and knows about your API is what you want it to see and know.
Technical writers and other DevRel positions are notoriously understaffed. This is a great time to hire talented writers and get them writing for AI instead of human readers.
Features and Docs are the Easy Part
Fleshing out your API and producing up to date, readable docs are things you should have been doing all along anyway. AI doesn’t change that, it merely raises the cost of poor software hygiene.
Once you get the table stakes out of the way, things get harder. Or at least take more effort.
Assume That AI Has No Idea What It Is Doing
AI is the ultimate expression of the developer attitude, “I don’t want to understand the business, I just want to code.” AI can’t understand the context and the customer can’t understand code. This model works out because this is sort of how most software is written anyway.
These are the conceptual shifts you need to make with your API to support AI development.
Make Your API Simple and Verifiable
Users are going to manually confirm API actions through the UI so your API needs to be simple and easy to verify. Endpoints that take multiple, open ended collections are great for performance and pushing a lot of data.
If they can partially succeed, customers will find them a nightmare as they try to understand the results of the AI’s code.
Lean on strong validation, all or nothing changes, and understandable error responses.
Things Are Going To Be Rerun. A Lot.
Everything will end up being rerun. Customers won’t understand data models and won’t understand the risks with rerunning things.
Embrace it by making everything as idempotent as possible.
Make non-idempotent actions all-or-nothing. AI is going to get close, a lot. The last thing your customers expect is for all that flailing to wreck their data. Bias the endpoints to either fully succeed or to take no action. Don’t do partial updates and then bail on the request. Change your processing to do full validation, and make changes only when you know you can make the full change.
Idempotent and all-or-nothing can be shockingly hard changes to implement. Fortunately, you can iteratively improve your API!
Error Messages Need To Be Non-Developer Readable
Put effort into making your errors human readable and reasonable. AI is better at grokking text than dense error responses.
Even better, when something fails validation include a link to the documentation where you’ve explained the correct structure.
Shifting to An AI First API Takes Time
Shifting to an AI first API isn’t complicated, but it will take time and effort.
Start with the fundamentals – make all of your features available through your API, and get your documentation up to date. Then, if need be, work to make you API AI friendly.
Customers are going to bring their own AI to your API and do amazing new things that you would never have imagined. Embrace the change.
