Fost Singapore 2026 - Designing APIs That Humans Love By David Sojevic.

In this talk, the speaker, a senior software engineer, discusses the importance of designing APIs that prioritize human usability to ensure successful adoption, particularly in the context of AI integration. He emphasizes that while the current trend focuses on AI-first development, it is humans who ultimately choose and interact with APIs. The speaker provides insights into creating user-friendly documentation and clear value propositions, highlighting the need for easy access to API functionality and straightforward integration processes. He uses examples from companies like Stripe and Twilio to illustrate effective practices, such as offering interactive documentation and SDKs. Furthermore, the speaker touches on the significance of providing a robust developer experience post-integration to foster long-term engagement.

Uh hi everyone, my name is David. I'm a senior software engineer from AI and I'm here to talk today about designing that humans love and how following that AI will love it too. Uh so the current narrative is very much like AI first everything agents are going to be using your APIs. Um, and if you don't do all of this, you're going to start to fall behind.

Um, but I want to sort of challenge this narrative a little bit. Um, and talk about how I think current reality is that AI doesn't adopt your AI. Uh, your API, sorry, uh, people do. So, right now, humans choose what APIs they're going to use. Humans are paying for them. Humans and increasingly AI these days are integrating them. Uh, and humans and AI are debugging them. increasingly.

So the problem right now is I don't think we've necessarily solved human usability. Um AI APIs are hard to uh try often. Uh they can be difficult to understand and reason with and they often can have inconsistent behavior depending on when they were designed and implemented and things like that. Um, and I think actually going back to the open banking thing, uh, they've addressed problems that I've

seen over the last years, um, very well. So, I'm glad you you guys brought it up. Uh, so yeah, I think the different perspective is more just that we do uh, human first uh, means it's AI ready. I don't think they're separate goals at all. I think doing things for humans will support the same foundations uh, that AI will require. So I think the first focus um

for APIs is making the value in your API obvious um not not everyone's AI APIs uh are immediately obvious how to be used um things like banking obviously other people in the fintech sector will know what they're what they want and what they're after um smaller services and things like that uh you may have to sell it a bit but if you can make that value obvious

to people coming to your product and your website. Um that that helps in the adoption that discoverability phase. So what what I think this looks like um is that before anyone really believes uh or before anyone really integrates your product, they have to believe in what your product does and what your API does. Um so things like outcomeled landing pages. Um so if you first thing you

land on the website is sort of showing you what you can do with the product, what you can do with the API and how it's used. Um things like clear use cases uh either on the landing page or easily accessible from it, sample outputs. Um and then the other things uh sort of adjacent to this are clear signs of reliability and support. So how are you supporting

your API? uh do you have things like statuses and down times and uh easy support and access and things like that? Are you transparent in what you're offering? Uh and this this is important not just for like developers but for uh people making decisions, PMs and CTOs and everything like that. The the second one I think is uh time to first success with an API. Um, so

how long does it take before generally a developer or even someone assessing it from outside of the the engineering team, how long does it take for them to make a successful request with your API? Um, when your API is easy to use and they can get their first success easily. Uh, it increases the likelihood of adoption. Um, you know, sometimes even uh APIs are discovered by the

developers and floated upwards through the team. uh and it's increasingly um more valuable to you to be able to do that. So what what good looks like here uh are things like interactive examples um on your website, things like pre-filled requests that you can go on and just maybe alter a value and hit send and it'll do something. uh ideally the ability to try without signing up

whether or not that's a real request not always possible or a mocked request just so you can see what the what the flows like and just generally getting immediate feedback from the API. So one of my favorite examples for this is uh Stripe documentation. So, if you go into the Stripe documentation, uh, you'll see front and center they've got a try it out panel. Um, and it's

effectively a copy of their CLI mocking all of the data. You can go in and immediately send a request and see what the request looks like and what the response comes back and they've got different examples on the left hand side there. So, you can see maybe use case driven examples. So, you know, if you want to start a checkout, if you want to sell a product

and things like that, you can see how to do it without signing up, without reading through hundreds of pages of documentation or guides or anything like that. Uh, next is ourselves. I think uh we're pretty proud of uh our interactive playground embedded right on the homepage, too. So, this is this is a a screenshot of our homepage right here. Um, you can see in the the first

few hundred pixels, um, you can jump in and try out our product straight away. Um, you don't need to be signed in. It it's it's immediately obvious what it does when you do it. Uh, and you can see, you know, in the first 30 seconds, is our API going to be valuable to what you want and what you need? And then inversely, uh, things that could slow

adoption of your API, uh, are things like no clear starting point. um whether or not you have to have a force sign up first. Um some services obviously require that you know maybe confidentiality. Uh others don't need it but just have it as a gating mechanism and otherwise like long setup processes. Um if someone has to sign up and then can't actually try it for another day

or two. Um you know it just slows down whether or not they like it or whether or not they can even adopt it or try it. Uh the next one is um documentation for for an API is um the UI effectively. Um so good documentation is is use case driven. There are clear examples all throughout it. Uh table stakes for this sort of thing is request and

response pairs and error explanations. Uh a good example of this is is GitHub um is they've actually got a very very comprehensive documentation covering off um you know just very dry API implementation um to quick start guide so if you have to do uh one thing in particular and and everything from there too they've got SDKs and libraries and other other resources that someone implementing it might

need um even to see if they want to explore other areas of the API they're not currently using they can see how they might be able to get that value out of things that can overwhelm users or display them. Um, it just if you have an endpoint dump with no explanation around anything, if you have examples or no examples I should say in there, um, or examples

with no context or no guidance around them, uh, no explanations. Uh, and actually one of the largest things that can be really overwhelming or discouraging is outdated documentation. So if your API is doing one thing and your documentation is saying that it can do something else, um that can confuse people and frustrate them and lead to additional support or just abandonment of your API in general. Uh

if if a user has to guess what's going to happen, um they might not use your API. Uh this leads into no bad surprises. So what this means is that um instead of being like clever or um unknown, you want to be reliable and this is things like consistent naming and patterns. So from endpoint to endpoint um if you're referring to an entity type, you want to

make sure the naming and you know even the pluralization can be consistent between them because moving from one to another it's easy source of confusion. Um if things change, you want stable response shapes. how the API responds from various things. You want areas that explain either what to do next um or are clear enough that they have information on how you can act upon them. And if

you're sort of rapidly developing your your product, um you want a clear versioning and deprecation policy in place. So someone adopting your AI API knows that what they're doing today um will either still be usable in 12 months time uh or if it's not they know when they have to sort of try and shift off it. Um focus number four is making integration boring. Uh and not

in the sense that you're hating life when it's happening. Um but in the sense that you don't have to think too hard about when you're implementing uh an API. Uh what helps in this thing is things like official SDKs that you're offering in libraries. Uh open API spec and swagger specs that you can easily distribute postman collections. official connections like the NA10 and the Boommy uh and

then example tutorials and guides. Um and and these things all sort of help allow the people integrating to decide what best suits their team and how they use it. Some people might use the open API spec for uh using code generation tools. Some people might use postman collection because they want to open product or API um just beforehand to see how it works and see see what

the shape of it is. Some people need no code or low code solutions. So a connector that they can just sort of go in and and and connect out of the box will will work well. Um so wrong picture but Twilio if I have a picture here. Twilio actually offers official SDKs. Um and They've got a whole lot of them and you can check them out and

use them too. Uh, Discord is one of the other ones. They have Postman collections. You can go showing their primary HTTP APIs and their gateway APIs and you you can also, you know, sort of just explore and poke and pro at the API that way. Uh, now in terms of AI, uh, there are extras you can go and do above and beyond. That's things like MCB servers

for guided tooling access. uh things like downloadable skills or packaged workflows that you can let people get and even as simple as serving AI friendly markdown um for your documentation pages or your general pages. So uh when something like the city or open AI comes and um queries your site they can read it in an easy format without all of the markdown uh sorry markup that uh

HTML would offer Uh then the last focus point here is developer models. Um so just getting into your API at the start is not really the finish line. It's just the first step in the relationship. Um if the the follow-up experience is weak, the whole product starts to feel a bit fragile. Um even if the API is good. So what good looks like here and I'm really

glad again that um open banking had a presentation here because they they exhibited a lot of this uh before um the ability to do things like managing keys and permissions from the UI um seeing usage and limits and and building clearly uh and reviewing recent requests and actions um the ability to download your specs like open API specs, swagger specs, postm collections all from the UI. it

make it really easy for people to come in and use it. Um and on top of this if you have things like that uh with permissions especially you can let uh nontechnical roles come in and also manage your or review. So you can have your accounts come in there review billing and usage you can have your your PMs or your Pers come in and check that out

too. Uh so a really good example of this is the Stripe developer dashboard. Um, so in amongst their general general dashboard, they've got the develop developer section. Uh, it gives you all of the main things you want in there. Gives you API key management access. It gives you access to web hooks. Um, which are another great one if if your product sort of has that sort of

um out of band cycle to to support. It gives you uh visibility into events and logs and requests that you make. So you can go through and see what what's been happening in your API. Um, especially valuable now if you've got AI using it, you didn't make the request, you maybe don't have access to a log of that request. If you can go onto your developer portal

and see what actions occurred, what the outcome was, what went into it, uh, it makes it really easy to to assist and aid in that sort of development process. Um, yeah, and that's all I have there. So, thank you everyone for the time. Um,