Harnessing BDD & Example Mapping for effective API delivery #apidays
A presentation at APIDays Paris in December 2023 in Paris, France by Frank Kilcommins
Harnessing BDD & Example Mapping for effective API delivery #apidays
I’m Frank Kilcommins › › › › Principal API Technical Evangelist @ SmartBear Developer and Architect ( APIs & Developer Experience) Governance Board member on OpenAPI Initiative (OAI) Contributor on Workflows Specification › Connect: @fkilcommins @frank-kilcommins frank.kilcommins@smartbear.com /* insert embarrassing photo here */
Talk Track › › › › Why APIs Fail - The People Problem Leveraging BDD & API Specifications for API delivery Takeaways Q&A
The People Problem… › Organizational challenges Technology focus dominates rather than people and process. (This graphic reflects Integrated Automation but is also true for APIs)
Alignment Gap › Only 48% are confident their APIs are well documented and explain value for consumers Our APIs are well documented for our consumers Agree 38% Neutral 30% Disagree 16% Strongly Agree 10% Strongly Disagree 2023 5% 0% 10% 20% 30% 2021 40% Our organization has good processes in place to ensure APIs can be efficiently consumed › ~43% unsure their processes will deliver appropriate developer experience (DX) Agree 45% Neutral 27% Disagree 12% Strongly Agree 12% Strongly Disagree 2023 2021 4% 0% 5% 10% 15% Source: SmartBear – State of Software Quality | API 2023 20% 25% 30% 35% 40% 45% 50%
Playlist for the modern API program
./BDD for API Delivery BDD for API Delivery
Business Rules Where are the API requirements?
Business Rules Acceptance Criteria Where are the API requirements?
Acceptance Criteria Business Rules Where are the API requirements? Test Plan
Acceptance Criteria Business Rules Where are the API requirements? Test Plan Napkins to Code with annotations
BDD for API Delivery
./API Specifications API Specifications
Popular API related Specifications WSDL | WADL | RAML | API Blueprint
Let Specifications Drive the API Lifecycle Implementation Generated server code / models Mocking Testing Prototyping Functional, security, load, compliance etc. Design Virtualization Reuse, linking, callbacks Functional/Runtime, use-case simulations Clients Documentation Generated libraries Developer Portals, code examples, user guides, support, etc. Deployment/Runtime Security, usage policies, monitoring, caching, rate-limiting, metrics etc.
“Good specifications will always improve programmer productivity far better than any programming tool or technique.” - Milt Bryce
BDD for API Delivery
BDD for API Delivery
BDD for API Delivery
Example Mapping for Deliberate Discovery › Effectively explore and refine detailed acceptance criteria so that: › › › › Agreed the scope Identified as much uncertainty as possible Agreed on the readiness for design/development Identified concrete examples
Example Mapping for Deliberate Discovery › Effectively explore and refine detailed acceptance criteria so that: › › › › Agreed the scope Identified as much uncertainty as possible Agreed on the readiness for design/development Identified concrete examples Unknown unknowns
Example Mapping for Deliberate Discovery › Effectively explore and refine detailed acceptance criteria so that: › › › › Agreed the scope Identified as much uncertainty as possible Agreed on the readiness for design/development Identified concrete examples Unknown unknowns Known unknowns
Example Mapping for Deliberate Discovery › Effectively explore and refine detailed acceptance criteria so that: › › › › Agreed the scope Identified as much uncertainty as possible Agreed on the readiness for design/development Identified concrete examples Unknown unknowns Known unknowns Known knowns
USER STORY RULE EXAMPLE EXAMPLE EXAMPLE RULE RULE EXAMPLE EXAMPLE EXAMPLE QUESTION? ASSUMPTION
Who should participate? The traditional 3 Amigos
Who should participate? API Designer * The traditional 3 Amigos API Architect * Enhanced with API specific SMEs * dedicated or floating from a C4E
Practical API Governance › Are we building the right API? › Are we building the API right?
Creating a Pet Adoption Service Problem: We’re overwhelmed by the number of pets being abandoned at our pet store. Solution: Following research and evaluation, we’ve decided to create the ability to search for and adopt pets that we catalog. We’ll offer the service via our website but also with a wider eco-system of shelters, charities, and pet orphanages. Photo by Thomas Park on Unsplash
Creating a Pet Adoption Service Problem: We’re overwhelmed by the number of pets being abandoned at our pet store. Solution: Following research and evaluation, we’ve decided to create the ability to search for and adopt pets that we catalog. We’ll offer the service via our website but also with a wider eco-system of shelters, charities, and pet orphanages. Photo by Thomas Park on Unsplash
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL SUMMARY DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED A PET SUMMARY SHOULD HAVE: NAME, ID, STATUS, CATEGORY, BREED, LOCATION
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL PAGED SUMMARY DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED A PET SUMMARY SHOULD HAVE: NAME, ID, STATUS, CATEGORY, BREED, LOCATION SEARCHING PETS MUST SUPPORT PAGINATION (PAGED RESULTS & PARAMETERS)
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL PAGED SUMMARY DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED JANE SEARCHES FOR ADOPTED STATUS PETS => PAGED SUMMARY OF ADOPTED PETS RETURNED A PET SUMMARY SHOULD HAVE: NAME, ID, STATUS, CATEGORY, BREED, LOCATION SEARCHING PETS MUST SUPPORT PAGINATION (PAGED RESULTS & PARAMETERS)
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL PAGED SUMMARY DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED JANE SEARCHES FOR ADOPTED STATUS PETS => PAGED SUMMARY OF ADOPTED PETS RETURNED JANE SEARCHES FOR PETS LOCATED IN GALWAY => PAGED SUMMARY OF GALWAY LOCATED PETS RETURNED A PET SUMMARY SHOULD HAVE: NAME, ID, STATUS, CATEGORY, BREED, LOCATION SEARCHING PETS MUST SUPPORT PAGINATION (PAGED RESULTS & PARAMETERS)
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL PAGED SUMMARY DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED JANE SEARCHES FOR ADOPTED STATUS PETS => PAGED SUMMARY OF ADOPTED PETS RETURNED JANE SEARCHES FOR PETS LOCATED IN GALWAY => PAGED SUMMARY OF GALWAY LOCATED PETS RETURNED JANE SEARCHES CATS => PAGED SUMMARY OF CATS REGARDLESS OF LOCATION, STATUS, OR BREED RETURNED A PET SUMMARY SHOULD HAVE: NAME, ID, STATUS, CATEGORY, BREED, LOCATION SEARCHING PETS MUST SUPPORT PAGINATION (PAGED RESULTS & PARAMETERS)
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL PAGED SUMMARY DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED A PET SUMMARY SHOULD HAVE: NAME, ID, STATUS, CATEGORY, BREED, LOCATION JANE SEARCHES FOR ADOPTED STATUS PETS => PAGED SUMMARY OF ADOPTED PETS RETURNED JANE SEARCHES FOR PETS LOCATED IN GALWAY => PAGED SUMMARY OF GALWAY LOCATED PETS RETURNED JANE SEARCHES CATS => PAGED SUMMARY OF CATS REGARDLESS OF LOCATION, STATUS, OR BREED RETURNED JANE SEARCHES FOR BOXER BREED CATS => AN EMPTY RESPONSE IS RETURNED SEARCHING PETS MUST SUPPORT PAGINATION (PAGED RESULTS & PARAMETERS) WHEN CRITERIA DOES NOT MATCH A PET RETURN EMPTY RESPONSE (NOT ERROR)
SEARCH FOR PETS CALLING THE SEARCH PETS RESOURCE RETURNS ALL AVAILABLE PETS JANE CALLS THE SEARCH PETS RESOURCE => ALL PAGED SUMMARY DETAILS OF AVAILABLE PETS ARE RETURNED PETS CAN BE FILTERED BY STATUS, CATEGORY, LOCATION, & BREED A PET SUMMARY SHOULD HAVE: NAME, ID, STATUS, CATEGORY, BREED, LOCATION JANE SEARCHES FOR ADOPTED STATUS PETS => PAGED SUMMARY OF ADOPTED PETS RETURNED JANE SEARCHES FOR PETS LOCATED IN GALWAY => PAGED SUMMARY OF GALWAY LOCATED PETS RETURNED JANE SEARCHES CATS => PAGED SUMMARY OF CATS REGARDLESS OF LOCATION, STATUS, OR BREED RETURNED JANE SEARCHES FOR BOXER BREED CATS => AN EMPTY RESPONSE IS RETURNED SEARCHING PETS MUST SUPPORT PAGINATION (PAGED RESULTS & PARAMETERS) JOE SEARCHES 1 PAGE OF PETS WITH 10 PER PAGE * PAGE PARAMS VALIDATED => A PAGED RESULT CONTAINING 10 PETS WITH LINKS TO NEXT/SELF/PREVIOUS PAGES RETURNED WHEN CRITERIA DOES NOT MATCH A PET RETURN EMPTY RESPONSE (NOT ERROR)
What does formulation look like? Check out: https://www.youtube.com/watch?v=L8HjnzOmhV4
VIEW PET DETAILS THE FULL PET DETAILS CAN BE RETURNED ONCE THE PETID IS KNOWN JANE HAS THE PETID AND USES IT TO GET THE PET DETAILS => FULL DETAILS ON THE PET RETURNED JOE USES THE NAME OF A PET TO GET THE DETAILS => A BAD REQUEST RESPONSE IS RETURNED JOE HAS A PETID BUT IT DOES NOT MATCH A RECORD IN OUR SYSTEM => A NOT FOUND RESPONSE IS RETURNED REQUEST PARAMETERS MUST MATCH THE EXPECTED TYPE OR PATTERN VALID REQUESTS ON SINGULAR RESOURCE NOT MATCHING A RECORD MUST RETURN 404
AUTHENTICATED USERS CAN ADD NEW PETS FOR ADOPTION JANE HAS AN AUTH TOKEN AND SENDS A NEW PET RECORD * REQUEST VALIDATED => A SUCCESSFUL RESPONSE IS RETURN INCLUDING THE PET RESOURCE JOE TRIES TO CREATE A PET BUT FORGETS HIS TOKEN => A UNAUTHORIZED REPONSE RETURNED ADD A NEW PET A NEW PET MUST HAVE AT LEAST NAME, CATEGORY, BREED, AND LOCATION SET JOE SENDS A NEW PET RECORD WITH JUST NAME AND CATEGORY * REQUEST VALIDATION FAILS => A BAD REQUEST IS RETURNED ALWAYS RETURN A HTTP 201 RESPONSE FOR CREATED RESOURCES JOE SENDS A NEW PET RECORD THAT MEETS VALIDATION RULES => A HTTP 201 RESPONSE IS CREATED WHICH ALSO CONTAINS THE PET RECORD ALWAYS RETURN A LOCATION HTTP RESPONSE HEADER FOR CREATED RESOURCES JOE SENDS A NEW PET RECORD THAT MEETS VALIDATION RULES => THE RESPONS CONTAINS A LOCATION HEADER WITH THE LINK TO THE GET /PETS/{ID} ERROR RESPONSES MUST CONFORM TO RFC 7807
ADOPT A PET AVAILABLE PETS CAN BE ADOPTED BY REGISTERED USERS JANE IS REGISTERED AND CHOOSED TO ADOPT AN AVAILABLE PET => THE ADOPTION IS REGISTERED, THE PET STATUS IS UPDATED, AND A CONFIRMATION IS RETURNED TO JANE JOE TRIES TO ADOPT AN ADOPTED PET => AN ERROR IS RETURNED WITH INFO THAT THE PET IS UNAVAILABLE FOR ADOPTION SALLY IS UNREGISTERED AND TRIES TO ADOPT A PET => AN ERROR MESSAGE IS RETURNED TO SALLY AS SHE MUST BE REGISTERED JOE TRIES TO ADOPT AN UNKNOWN PET => A 404 NOT FOUND ERROR IS RETURNED TO JOE SHOULD A 401 UNAUTHORISED OR 403 FORBIDDEN STATUS BE RETURNED FOR UNREGISTERED?
GET PET ADOPTIONS LIST A REGISTERED USER CALLING THE SEARCH ADOPTIONS ALL RECORDED ADOPTIONS JANE IS REGISTERED AND CALLS THE SEARCH ADOPTIONS RESOURCE => PAGED SUMMARY OF ADOPTIONS RETURNED JOE SEARCHES FOR ADOPTIONS BUT OMITS TOKEN => AN UNAUTHORIZED RESPONSE IS RETURNED ADOPTIONS CAN BE FILTERED BY STATUS, AND LOCATION JANE SEARCHES FOR ADOPTIONS WITH PENDING STATUS => PAGED SUMMARY OF PENDING ADOPTIONS RETURNED JOE SEARCHES FOR INACTIVE ADOPTIONS => AN ERROR IS RETURNED AS INVALID IS NOT AN ADOPTION STATUS JOE SEARCHES FOR ADOPTIONS WITH A COLOUR=RED => A PAGED SUMMARY OF ADOPTIONS RETURNED A ADOPTION CAN HAVE STATUS OF REQUESTED, PENDING, AVAILABLE, DENIED, APPROVED UNKNOWN QUERY PARAMETERS SHOULD BE IGNORED
Can we do more with “Examples”?
Most Important API Documentation Features? › Examples continue to be the best learning resource for consumers SmartBear – State of Software Quality | API 2023
Most Important API Documentation Features? › Examples continue to be the best learning resource for consumers SmartBear – State of Software Quality | API 2023
What does example-enriched formulation look like? Check out: https://www.youtube.com/watch?v=L8HjnzOmhV4
Summary › › › › Focus on the consumer and the behaviour they need Keep people at the center of API delivery Human conversations & techniques like example mapping work Collaboration is key to delivering good Developer Experience › Remember: Your API is a promise, let it tell its story!
Thank You! Questions? › Connect: @fkilcommins @frank-kilcommins frank.kilcommins@smartbear.com
