To empower developers to consume Web APIs to fulfill the use-cases they care about.
A Coruña, Spain
Joined December 2006
- Tweets11.2K
- Following0
- Followers6.7K
- Likes1.8K
Pinned Tweet
"most people who believe they work in API Design are actually working on technical API definition" brunopedro.com/2019/08/27/no…
Knowing how to define a multi-step Arazzo workflow is not the same as being able to execute it.
What are the available options for running Arazzo engine workflows?
apichangelog.substack.com/p/…
"You’re saying the highest form of a good API is when it gets used in ways nobody intended," wrote Shane O'Connor in Off Spec nº 02. "How do you design for it without designing it away?"
Here's my answer: teamapiwiz.substack.com/p/of…
API User Experience or, in short, APIUX is the experience of any user of your API.
In 2020, I wrote that "your API’s User Experience can be broken down into developers and third-party application end users."
Today, I'd add Agents to that list.
brunopedro.com/2020/11/22/ap…
It's the second day in a row that someone has sent me a message that mentions the Chatham House rule.
AI agents can discover, make requests, and combine API operations, all on their own.
But they often fail to understand what an API does and how to use operations in more sophisticated workflows.
apichangelog.substack.com/p/…
AX, or agentic experience, is the measure of how easily an AI agent can understand and use an API.
If your API offers a good AX, AI agents will be able to find it and use it easily. You'll get more users and, even better, more repeated usage.
apichangelog.substack.com/p/…
Tackling a bunch of security-related alerts on the swagger-ui diff highlight plugin.
github.com/InditexTech/swagg…
Forget all you learned about developer experience.
Now, API design is not just about helping people build integrations. Now what matters the most is making sure that AI agents have as smooth an experience as possible.
apichangelog.substack.com/p/…
User journeys usually start with one or more requests to a REST API followed by events.
You think in terms of capabilities, not protocols.
Why do we document synchronous and event-driven APIs separately?
apichangelog.substack.com/p/…
What is the unit of value in APIs?
If you were to create an API marketplace, what would you target as the unit of value?
Ultimately, consumers want the capabilities provided by the APIs, not the APIs themselves.
notes.brunopedro.com/2023/06…
Are you using swagger-ui to render your OpenAPI description?
You might be interested in something I've been building that shows API diffs inline: github.com/InditexTech/swagg…
Reading isn’t enough when you want to learn something new.
To actually learn how to do something, you need to try it. Perhaps you’ll fail a few times, but that’s all part of the learning process.
apichangelog.substack.com/p/…
Sooner or later, every change you introduce to your API will break the integration with at least one consumer.
The interface stops being the interface. Hyrum goes further and says the "interface has evaporated."
apichangelog.substack.com/p/…
I can see this flow for AI-enabled Product Development producing great results:
User Interviews → Problem Discovery → User Story Distillation → SDD → Verification against Acceptance Criteria → Delivery
The challenge with agentic workflows and stateless APIs is related to the need to handle user input as a response to a request.
The solution seems to be doing “multi round-trip requests” using something called InputRequiredResult.
apichangelog.substack.com/p/…
Should agents generate integration code once or let AI figure out how to consume APIs whenever they need to?
These two choices are, in fact, a false dichotomy.
apichangelog.substack.com/p/…
Creating a new OpenAPI extension is as easy as starting a property name with the x- string.
But what happens when two or more extensions pick the same property name?
apichangelog.substack.com/p/…
