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

Creating the new: adidas APIs

Z
October 11, 2017

Creating the new: adidas APIs

The talk was given by Oldrich Novak and Zdenek Z Nemec at Nordic APIs, Stockholm. October 11th, 2017.

Z

October 11, 2017
Tweet

More Decks by Z

Other Decks in Technology

Transcript

  1. https://youtu.be/kyum6GZp3r4

    View full-size slide

  2. CREATING 
    THE NEW
    ADIDAS APIS
    ZDENEK “Z” NEMEC
    OLDRICH NOVAK
    https://goodapi.co
    @zdne
    GOOD
    API
    [email protected]

    View full-size slide

  3. SPORTS
    COMPANY

    View full-size slide

  4. PAST‐ADIDAS
    APIS

    View full-size slide

  5. LACK OF
    VISIBILITY
    AND
    GOVERNANCE

    View full-size slide

  6. LACK OF
    CONSISTENCY
    AND
    QUALITY

    View full-size slide

  7. LACK OF
    OWNERSHIP

    View full-size slide

  8. LACK OF
    BUSINESS FOCUS
    API DESIGN FOLLOWING TECHNOLOGY
    NOT BUSINESS NEEDS

    View full-size slide

  9. COMPLEX
    PROCESSES
    EXPOSING FUNCTIONALITY FOR CLIENTS

    View full-size slide

  10. THE PROMISED LAND

    View full-size slide

  11. REUSE OF EXISTING
    FUNCTIONALITY
    SINGLE SOURCE OF TRUTH
    COLLABORATION
    VISIBILITY
    Visibility

    View full-size slide

  12. CONSISTENT DEVELOPER
    EXPERIENCE WHILE
    CONSUMING APIS
    SUPERB
    EXPERIENCE
    Client DX

    View full-size slide

  13. SPEEDY DESIGN,
    DEVELOPMENT, TESTING AND
    PUBLISHING THROUGH
    STANDARDIZED AND HIGHL
    Y‐
    AUTOMATED PROCESSES
    FAST DELIVERY
    Fast
    Delivery
    Server DX

    View full-size slide

  14. PERFORMANCE,
    STABILITY &
    EXTENSIBILITY
    Performance
    Stability
    &
    Extensibility

    View full-size slide

  15. SECURITY
    Security

    View full-size slide

  16. CLEAR
    OWNERSHIP
    Ownership

    View full-size slide

  17. HOW DID 
    WE GET
    THERE
    HOW DID 
    WE GET
    THERE

    View full-size slide

  18. PEOPLE
    TOOLS
    PROCESSES

    View full-size slide

  19. TRAINED EXPERTS
    STANDARDIZED TOOLS
    AUTOMATED PROCESSES

    View full-size slide

  20. PEOPLE
    ORGANIZATION CHANGES, TRAININGS & THE ROLE
    OF THE API EVANGELIST

    View full-size slide

  21. ADIDAS API
    LIFECYCLE

    View full-size slide

  22. ADIDAS API LIFECYCLE
    1
    DESIGN
    DEVELOP
    &
    TEST
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    Prototype
    Feedback

    View full-size slide

  23. 1
    DESIGN
    DEVELOP
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    DESIGN
    API
    Visibility
    Client DX
    Stability
    &
    Extensibility

    View full-size slide

  24. API FIRST
    API IS PRODUCT

    View full-size slide

  25. DESIGN-FIRST
    API DESCRIPTION IS CONTRACT

    View full-size slide

  26. “The API description is the source of truth,
    NOT the API implementation.”

    View full-size slide

  27. SINGLE REPOSITORY
    FOR CONTRACTS
    Visibility

    View full-size slide

  28. DESIGN
    &
    IMPLEMENTATION
    MATURITY
    Client DX

    View full-size slide

  29. WEB API DESIGN
    MATURITY MODEL
    http://amundsen.com/talks/2016-11-apistrat-wadm/2016-11-apistrat-wadm.pdf
    Source:

    View full-size slide

  30. RESOURCE-CENTRIC
    DESIGN
    AT MINIMUM
    Web API Design Maturity Model Level 2

    View full-size slide

  31. AFFORDANCE-CENTRIC
    DESIGN
    IDEALL
    Y
    Web API Design Maturity Model Level 3

    View full-size slide

  32. RICHARDSON MATURITY
    MODEL
    https://martinfowler.com/articles/richardsonMaturityModel.html
    Source:

    View full-size slide

  33. HTTP PROTOCOL
    SEMANTICS
    AT MINIMUM
    Richardson Maturity Model Level 2

    View full-size slide

  34. HYPERMEDIA CONTROLS
    IDEALL
    Y
    Richardson Maturity Model Level 3
    Stability
    &
    Extensibility

    View full-size slide

  35. HYPERMEDIA SOLVES
    MANY DESIGN PATTERNS
    RELATIONS, COLLECTIONS, PAGINATIONS, EMBEDDING,
    VERSIONING AND BEYOND-CRUD OPERATIONS
    Stability
    &
    Extensibility

    View full-size slide

  36. HAL
    HYPERTEXT‐APPLICATION LANGUAGE

    View full-size slide

  37. HAL
    RMM Level 2 RMM Level 3

    View full-size slide

  38. DESIGN GUIDELINES
    Fast
    Delivery
    Client DX Security
    Stability
    &
    Extensibility

    View full-size slide

  39. DESIGN-TIME
    GOVERNANCE

    View full-size slide

  40. ADIDAS API GUIDELINES
    https://www.gitbook.com/book/adidas-group/api-guidelines/

    View full-size slide

  41. ADIDAS API GUIDELINES
    Protocol-level
    Message-level
    Application-level
    Functional Requirements
    Governance
    Non-Functional Requirements
    Governance
    Execution
    Evolution
    Security
    Usability
    Maintainability
    Scaleability
    Extensibility
    https://www.gitbook.com/book/adidas-group/api-guidelines/

    View full-size slide

  42. OPEN-SOURCED ON
    GITHUB
    Visibility
    https://github.com/adidas-group/api-guidelines

    View full-size slide

  43. DESIGN
    CONSISTENCY
    Client DX
    Fast
    Delivery
    HOW TO MAKE EVERYBODY FOLLOWS THE GUIDELINES

    View full-size slide

  44. AUTOMATED DESIGN
    CHECKS USING APIARY 
    STYLE GUIDE

    View full-size slide

  45. AUTOMATIC DESIGN
    GOVERNANCE

    View full-size slide

  46. 1
    DESIGN
    DEVELOP
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    DEVELOP &
    TEST‐API

    View full-size slide

  47. BOILERPLATES, TEMPLATES
    &
    GUIDELINES
    Fast
    Delivery
    Server DX

    View full-size slide

  48. SPRINGBOOT MICROSERVICE
    MAVEN ARCHETYPE

    View full-size slide

  49. CONTRACT
    VERIFICATION
    Fast
    Delivery
    Server DX

    View full-size slide

  50. DREDD — HTTP‐API
    TESTING FRAMEWORK

    View full-size slide

  51. CONTRACT VERIFICATION
    Dredd CLI
    API Description API Implementation
    Endpoint 1
    Endpoint 2
    Endpoint 3
    Endpoint 4

    View full-size slide

  52. JENKINS DREDD
    PLUGIN

    View full-size slide

  53. JENKINS DREDD+APIARY
    PLUGIN

    View full-size slide

  54. AUTOMATED SECURITY
    CHECK
    Security
    Work in
    Progress
    SECURITY‐AT THE SOURCE

    View full-size slide

  55. Performance
    Fast
    Delivery
    Server DX
    1
    DESIGN
    DEVELOP
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    DEPLOY
    API

    View full-size slide

  56. Security Ownership
    1
    DESIGN
    DEVELOP
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    PUBLISH
    API

    View full-size slide

  57. EXPOSE API USING
    MASHERY

    View full-size slide

  58. ARCHITECTURE

    View full-size slide

  59. ADIDAS API
    MANAGEMENT 
    GUIDELINES
    NAMING CONVENTIONS, PACKAGING, THROTTLING,
    AUTHENTICATION AND KEY POLICES

    View full-size slide

  60. MASHERY TOOLBELT
    Fast
    Delivery
    AUTOMATED API MANAGEMENT PROVISIONING USING THE
    API DESCRIPTION. FOLLOWING API MANAGEMENT 
    GUIDELINES

    View full-size slide

  61. MASHERY TOOLBELT
    https://www.npmjs.com/package/mashery-toolbelt
    Work in
    Progress
    https://github.com/adidas-group/mashery-toolbelt

    View full-size slide

  62. Client DX
    Stability
    &
    Extensibility
    1
    DESIGN
    DEVELOP
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    CONSUME
    API

    View full-size slide

  63. API
    DOCUMENTATION
    INTERACTIVE, CODE SAMPLES & DEBUGGING PROXY
    Client DX

    View full-size slide

  64. DEVELOPER PORTAL
    APPLICATION KEYS PROVISIONING, GETTING STARTED &
    USAGE PRINCIPLES
    Work in
    Progress
    Client DX

    View full-size slide

  65. DEVELOPERS PORTAL
    Work in
    Progress

    View full-size slide

  66. LOOSE COUPLING
    CLIENT MUST FOLLOW ROBUSTNESS PRINCIPLE, AND ACT
    INDEPENDENTL
    Y, NOT‐ASSUMING ANY INTERNAL
    IMPLEMENTATION OF THE SERVICE
    Client DX
    Stability
    &
    Extensibility

    View full-size slide

  67. Visibility
    1
    DESIGN
    DEVELOP
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    ANALYZE
    API

    View full-size slide

  68. AUTOMATED API
    AVAILABILITY TESTING 
    WITH RUNSCOPE

    View full-size slide

  69. Stability
    &
    Extensibility
    Client DX
    1
    DESIGN
    DEVELOP
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    UPDATE
    API

    View full-size slide

  70. CHANGES
    &
    VERSIONING

    View full-size slide

  71. –Mark Nottingham
    “The fundamental principle is that you can’t break
    existing clients, because you don’t know what they
    implement, and you don’t control them. In doing so,
    you need to turn a backwards-incompatible change
    into a compatible one.”

    View full-size slide

  72. NO URI VERSIONING
    https://blog.goodapi.co/
    https://blog.apisyouwonthate.com/

    View full-size slide

  73. RULES FOR EXTENDING
    • You MUST NOT take anything away (related: Minimal Surface
    Principle , Robustness Principle)
    • You MUST NOT change processing rules
    • You MUST NOT make optional things required
    • Anything you add MUST be optional (related Robustness
    Principle)

    View full-size slide

  74. CHANGE MANAGEMENT
    • Resource identifier including any query parameters and their
    semantics
    • Resource metadata
    • Action the resource affords
    • Relation with other resources
    • Representation format
    ANY‐CHANGE TO
    IS SUBJECT TO RULES FOR EXTENDING

    View full-size slide

  75. BACKWARD
    INCOMPATIBLE CHANGES
    IMPLIES NEW RESOURCE VARIANT
    /greeting?first=John&last=Appleseed
    /named-greeting?first=John&last=Appleseed
    first and last are optional but
    first needs to be made required

    View full-size slide

  76. ADIDAS API LIFECYCLE
    1
    DESIGN
    DEVELOP
    &
    TEST
    DEPLOY
    PUBLISH
    CON
    SUM
    E
    AN
    ALYZE
    2 3 4 5 6 7
    UPDATE
    Prototype
    Feedback

    View full-size slide

  77. FULL PICTURE

    View full-size slide

  78. AUTOMATED
    CONTRACT-DRIVEN API
    LIFECYCLE

    View full-size slide

  79. Bitbucket
    Apiary
    Jenkins
    Mashery API Gateway
    Mashery Cloud
    K8s Platfrom
    API Consumer
    Apiary Documentation
    Apiary Mock Service
    API Description
    API Description
    Service Implementation
    Apiary Style Guide
    Dredd Plug-in
    Apiary Test Reporter
    Apiary adidas team APIs
    Apiary Documentation
    Apiary Mock Service
    Analytics
    Admin
    Mashery Toolbelt
    2
    3
    4
    5
    6
    7
    1
    1 Design 2 Develop 3 Deploy 4 Publish 5 Use 6 Analyze 7 Update
    Security Checks
    Runscope Kibana

    View full-size slide

  80. http://goodapi.co/api-lifecycle

    View full-size slide

  81. THE FUTURE: REDESIGN B2B
    BUSINESS & ENABLE DIGITAL 
    CREATION THROUGH APIS

    View full-size slide

  82. COMPLETE B2B
    HAPPENING 
    THROUGH APIS

    View full-size slide

  83. DIGITAL 
    CREATION:
    CREATING 
    THE NEW

    View full-size slide

  84. THANK YOU
    ZDENEK “Z” NEMEC
    OLDRICH NOVAK
    https://goodapi.co
    @zdne
    GOOD
    API
    [email protected]

    View full-size slide

  85. Q&A
    ZDENEK “Z” NEMEC
    OLDRICH NOVAK
    https://goodapi.co
    @zdne
    GOOD
    API
    [email protected]

    View full-size slide

  86. https://www.karliekloss.com

    View full-size slide