Outside-in Development for APIs and Microservices

How to do emergent API Design with OpenAPI and Cucumber. Keynote at SmartBear Connect 2020, presented with Seb Rose (https://twitter.com/sebrose).
Code repo: https://github.com/sebrose/shouty.java-connect

Transcript

1. Outside-in Development for APIs and Microservices Emmanuel Paraskakis • Seb Rose
2. 2 How is software developed? BDUF | Silos | Handovers Agile | Collaborative | Incremental | Emergent
3. 3 How do APIs get developed? Service provider guesses what consumers will want? | Implement unneeded functionality | Don’t implement required functionality – rework often needed Consumers wait until API agreed / implemented | Dependencies / coupling | Waste
4. 4 Collaboration
5. 5 Collaboration
6. 6 Collaboration
7. 7 Collaboration
8. 8 Collaboration
9. 9 Collaboration Provider contracts | For international specs | Committees Consumer driven contracts | Within a company / ecosystem | Pact Emergent API development | Outside-in, lightweight, iterative | Highly collaborative teams
10. 10 State of API Design • Use of an API Definition Document (usually OpenAPI/fka Swagger) as a design artifact • Document serves as contract between Front-end and Back-end • Renders human-readable documentation • Drives a mock service for use as prototype
11. 11 Problems? • Presumes knowledge of HTTP protocol and OpenAPI DSL • Learning curve for business stakeholders and subject-matter experts • Tooling helps, but not during ideation phase
12. 12 API Lifecycle Developer Portal API Gateway Environment Sandbox API Consumer Domain Data Style Guide & Vocabulary API Description Document Collections & Scenarios Runtime Configuration change or deprecation
13. 13 State of BDD Collaborative specification of thin increments of behaviour | Building on agile approaches | Encouraging teams to iterate rapidly | Example Mapping widely used for structured collaboration Documenting business-readable examples of agreed behaviour | Widespread use of Gherkin (Given/When/Then) Turn examples into living documentation using automation tool | Cucumber and SpecFlow understand Gherkin | Ongoing confusion in marketplace between BDD and Test Automation
14. 14 3 core practices of BDD Discovery Create a shared understanding of the requirements through collaboration, typically achieved through a structured conversation centred on rules and examples Formulation Examples of system behaviourare documented using business terminology Automation The documentation is automated, creating living documentation that guides the system’s development and verifies its behaviour
15. 16 Outside-in • Would it make sense to use Gherkin & Example Maps for API Ideation? • We start by asking “what is the next behaviourto implement?” • Explored collaboratively with concrete examples • Documented using business terminology, SMEs can participate • Automated (Cucumber/SpecFlow, FIT/FitNesse etc.) • Failing documentation guides development & API Design • Just enough implementation to allow documentation to pass (stub is often enough) • Iterate (go back to top and pick the next behaviour)
16. 17 Demonstration domain - Shouty We are developing a new social media app - with some similarities to Twitter - called Shouty. Users of the app will be able to 'shout' a textual message. Users within 1000 metres of the shouter will be able to read ('hear') the message. Shouty service
17. 20 As a Shouty user I can communicate with people that are close to me, so that we can build a local community The range of a shout is 1000 metres C: Sean is 1200m from Lucy A: Sean shouts O: Lucy does not hear Sean C: Sean is 900m from Lucy A: Sean shouts O: Lucy hears Sean Business shouter can choose origin of a shout C: Sean is 1200m from Lucy A: Sean’s shout originates from a location 900m from Lucy O: Lucy hears Sean As a Shouty business user I can communicate with people that are close to my business premises, even when I am somewhere else Example mapping C: Sean is 900m from Lucy A: Sean’s shout originates from a location 1200m from Lucy O: Lucy does not hear Sean
18. 21 Formulate first scenario Scenario: In-range shout is heard GivenSean is at 0, 0 AndLucy is at 900, 0 WhenSean shouts ThenLucy should hear Sean
19. 22 Demo
20. 23 23
21. 31 Key Takeaways 1. Exploring ideas upfront is more effective, cheaper to do in ideation than in implementation 2. We can use BDD and API design together – business language 3. BDD is not Test Automation 3 1
22. 32 Resources • Get scenarios, OAS, code in GH repo – https://github.com/sebrose/shouty.java-connect • Learn more about BDD: • Free video courses – http://school.cucumber.io • BDD Books series http://bddbooks.com • Learn more about OpenAPI: • https://www.openapis.org/ • https://swagger.io/docs/specification/about/ • Products to help you: • https://cucumber.io/tools/cucumberstudio/ • https://swagger.io/tools/swaggerhub/
23. Thank you