INTERFACE by apidays 2023 - Refining Your API: The Last Mile of API Design, James Higginbotham, LaunchAny

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/

Transcript

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