Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Outside-in Development for APIs and Microservices

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

paraskakis

April 28, 2020
Tweet

More Decks by paraskakis

Other Decks in Technology

Transcript

  1. 2 How is software developed? BDUF | Silos | Handovers

    Agile | Collaborative | Incremental | Emergent
  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. 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
  8. 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
  9. 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)
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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/