INTERFACE by apidays 2023 APIs for a “Smart” economy. Embedding AI to deliver Smart APIs and turn into an exponential organization June 28 & 29, 2023 Refining Your API: The Last Mile of API Design James Higginbotham, Executive API Consultant at LaunchAny ------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/

1. Refining Your API:
The Last Mile of API Design
James Higginbotham
@launchany
Photo by Francisco Fernandes on Unsplash
bit.ly/refining-your-api

3. 2
@launchany
Introduction
•Consultant: API Strategy and Program Execution
•Speaker, Trainer, Author based in Colorado Springs, CO
•Author, “Principles of Web API Design: Delivering Value with APIs and Microservices”

4. Developer Experience

6. 5
@launchany
Framing the API’s purpose
1. Treat APIs like a conversation
Photo by Harli Marten on Unsplash

7. 6
@launchany
APIs are a Conversation: Machine-to-Machine
GET /projects
Accept: application/json
POST /projects
{ "projectName":"My Project", … }
GET /projects/12345
Accept: application/json
200 OK
Content-Type: application/json
[ { "projectId":"12344", … }, … ]
201 Created
Content-Type: application/json
Location: /projects/12345
200 OK
Content-Type: application/json
[ { "projectId":"12345", … }, … ]

8. 7
@launchany
APIs are a Conversation: Human-to-Machine

9. 8
@launchany
APIs are a Conversation: Developer-to-Developer
Examples
and Guides
Reference
Docs

10. 9
@launchany
APIs are a Conversation: Human-to-Human
Homeowner:
“Can you tell me where
we stand with my home
remodeling project?”
Project Manager:
“Sure, here are the
tasks completed and
items remaining, along
with budget details”

11. 10
@launchany
APIs are a Conversation: Human-to-Human
Policy Holder:
“I’m trying to list the
recently submitted claim so
that I can track the status
as I get back to whole”
Adjuster:
“Sure, I can provide you
with that information”

12. 11
@launchany
Does my API focus on
the conversation…
…or the data?

13. 12
@launchany
Find the outcome, problem, and job-to-be-done
2. Make your APIs intentional

14. 13
@launchany
Make Your APIs Intentional
2. Identify the
situation or
triggering event
3. Find the job to
be done that
delivers on the
desired outcome
1. Identify the
desired outcome

15. 14
@launchany
Make Your APIs Intentional
2. Identify the
situation or
triggering event
3. Find the job to
be done that
delivers on the
desired outcome
1. Identify the
desired outcome
Confirm the date that my order will arrive
I am uncertain of when my order will arrive
View the status of an order

16. 15
@launchany
Align to the Needs of the Consumer
Job Story: View Order Status
WHEN I am uncertain of when my order will arrive
I WANT TO View the status of my order
SO I CAN Confirm the date that my order will arrive

17. 16
@launchany
Job Stories Drive Acceptance Testing
Example: View Order Status Job Story
Given a user named ‘Donna’ with login ‘xyz@mycorp.com’
And an order created by user ‘Donna’ with the details ‘…’
And a login session for user ‘Donna’
When the user ‘Donna’ wants to know the status of an order
And user ‘Donna’ views the status of an order
Then ‘Donna’ should confirms the status of ‘Shipped’ with a
shipment date of ‘2023-06-27’ Desired outcome
Job to be done
Situation

18. 17
@launchany
Does my API deliver
on the desired
outcomes…
…or does it focus only
on the implementation
details?

19. 18
@launchany
Map processes, not data
3. Take it one step at a time

20. 19
@launchany
Maps Business Processes, Not Raw Data
•Using the outcomes as a guide, find the business processes necessary to deliver
upon the outcome
•Diagram out the process, or capture as a text-based narrative of each step

21. 20
@launchany
Does my API
support my
operational
model?

22. 21
@launchany
Focus on your API vocabulary
4. APIs should speak your domain

23. 22
@launchany
Model Your Domain

24. 23
@launchany
Use API Profiles to Model Your Domain

25. 24
@launchany
The Result: The Start of a Domain-Specific Language

26. 25
@launchany
Does my API
reinforce my
domain model
through a domain-
specific language
(DSL)?
Customer: listBooks() -> Books[]
Customer: addBookToCart(bookId) -> Cart
Customer: removeBookFromCart(bookId) -> Cart
Customer: searchBooks(searchQuery) -> Books[]
Customer: addBookToCart(bookId) -> Cart
Customer: viewCart() -> Cart

27. 26
@launchany
Listen to your API consumers regarding the API design style
5. Design with API consumers in mind

28. 27
@launchany
Today’s Popular API Styles and Protocols

29. 28
@launchany
Uni-Directional and Bi-Directional Webhooks
Webhook
Dispatcher
Workflow
Engine
Messaging
App
Webhook
Receiver
Webhook
Receiver
Webhook
Dispatcher
HTTP POST /hooks/messages
HTTP POST /hooks/workflow
{
“lastState”: “review”,
“newState”: “approved”,
“workflowId” : …
}
{
“message”: “Can you please review?”,
“link”: “/articles/12345”,
“workflowId” : …
}
Ash: “Can you please review?”
Julie: Approved
1 2
1
2

30. 29
@launchany
Server-Sent Events
Source: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
App API
Here you go!
Here you go!
Here you go!
GET /streams/users
Last-Event-ID: message-1234
Here you go!
… time elapses …

31. 30
@launchany
Websocket
API Consumer
Web/Mobile/Server
HTTP/1.1 101 WebSocket Protocol Handshake
Date: Thu, 10 Sept 2020 14:53:18 GMT
Connection: Upgrade
Upgrade: WebSocket
…
GET ws://echo.websocket.org/?encoding=text
Origin: http://websocket.org
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
… WebSocket upgrade response
Hello, client
REST API Server
with WebSocket
support
WebSocket upgrade request
<<WebSocket Enabled>>
Hello, server.

32. 31
@launchany
GraphQL Subscriptions
Source: https://graphql.github.io/graphql-spec/June2018/#sec-Subscription

33. 32
@launchany
gRPC Client and Server Streaming
gRPC Client gRPC Server
service Main {
rpc GetLatestOrders(stream OrderQuery)
returns (OrderResults) {}
}
gRPC Async Option 1: Client Streams to Server
gRPC Client gRPC Server
gRPC Option 2: Server Streams to Client
service Main {
rpc GetLatestOrders(OrderQuery)
returns (stream Order) {}
}
gRPC Client gRPC Server
gRPC Async Option 3: Bi-Directional streaming
service Main {
rpc GetLatestOrders(stream OrderQuery)
returns (stream Order) {}
}

34. 33
@launchany
Design with API Consumers in Mind

35. 34
@launchany
Does my API
consider the
needs of my API
consumers?

36. 35
@launchany
Fast feedback with README-style mocking
6. A mock is worth a thousand words

37. 36
@launchany
API Sequence Diagrams

38. 37
@launchany
Example of a README Mock: Step 1

39. 38
@launchany
Example of a README Mock: Step 2

40. 39
@launchany
Have I explored
how my API
delivers outcomes
through mocks?

41. 40
@launchany
7. Putting it all together

42. 41
@launchany
Design the digital capabilities as APIs, events, and streams
DESIGN
Seek stakeholder alignment on desired outcomes
ALIGN
Improve the design based on early feedback
REFINE
Agree on digital capabilities required for desired outcomes
DEFINE
The ADDR Collaborative API Design Process
Human-to-
Human
Human-to-
Human
Developer-to-
Developer
Machine-to-
Machine

43. 42
@launchany
Thank You!
James Higginbotham
@launchany
james@launchany.com
bit.ly/refining-your-api