Creating the new: adidas APIs

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

Transcript

1. https://youtu.be/kyum6GZp3r4
   

   View Slide

2. CREATING 
   THE NEW
   ADIDAS APIS
   ZDENEK “Z” NEMEC
   OLDRICH NOVAK
   https://goodapi.co
   @zdne
   GOOD
   API
   oldrich.novak@adidas-group.com
   

   View Slide

3. SPORTS
   COMPANY
   

   View Slide

4. TECH
   COMPANY
   

   View Slide

5. PAST‐ADIDAS
   APIS
   

   View Slide

6. LACK OF
   VISIBILITY
   AND
   GOVERNANCE
   

   View Slide

7. LACK OF
   CONSISTENCY
   AND
   QUALITY
   

   View Slide

8. LACK OF
   OWNERSHIP
   

   View Slide

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

   View Slide

10. COMPLEX
    PROCESSES
    EXPOSING FUNCTIONALITY FOR CLIENTS
    

    View Slide

11. THE PROMISED LAND
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

15. PERFORMANCE,
    STABILITY &
    EXTENSIBILITY
    Performance
    Stability
    &
    Extensibility
    

    View Slide

16. SECURITY
    Security
    

    View Slide

17. CLEAR
    OWNERSHIP
    Ownership
    

    View Slide

18. HOW DID 
    WE GET
    THERE
    HOW DID 
    WE GET
    THERE
    

    View Slide

19. PEOPLE
    TOOLS
    PROCESSES
    

    View Slide

20. TRAINED EXPERTS
    STANDARDIZED TOOLS
    AUTOMATED PROCESSES
    

    View Slide

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

    View Slide

22. ADIDAS API
    LIFECYCLE
    

    View Slide

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

    View Slide

24. 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 Slide

25. API FIRST
    API IS PRODUCT
    

    View Slide

26. DESIGN-FIRST
    API DESCRIPTION IS CONTRACT
    

    View Slide

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

    View Slide

28. SINGLE REPOSITORY
    FOR CONTRACTS
    Visibility
    

    View Slide

29. DESIGN
    &
    IMPLEMENTATION
    MATURITY
    Client DX
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

37. HAL
    HYPERTEXT‐APPLICATION LANGUAGE
    

    View Slide

38. HAL
    RMM Level 2 RMM Level 3
    

    View Slide

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

    View Slide

40. DESIGN-TIME
    GOVERNANCE
    

    View Slide

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

    View Slide

42. 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 Slide

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

    View Slide

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

    View Slide

45. AUTOMATED DESIGN
    CHECKS USING APIARY 
    STYLE GUIDE
    

    View Slide

46. AUTOMATIC DESIGN
    GOVERNANCE
    

    View Slide

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

    View Slide

48. BOILERPLATES, TEMPLATES
    &
    GUIDELINES
    Fast
    Delivery
    Server DX
    

    View Slide

49. SPRINGBOOT MICROSERVICE
    MAVEN ARCHETYPE
    

    View Slide

50. CONTRACT
    VERIFICATION
    Fast
    Delivery
    Server DX
    

    View Slide

51. DREDD — HTTP‐API
    TESTING FRAMEWORK
    

    View Slide

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

    View Slide

53. JENKINS DREDD
    PLUGIN
    

    View Slide

54. JENKINS DREDD+APIARY
    PLUGIN
    

    View Slide

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

    View Slide

56. 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 Slide

57. View Slide

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

    View Slide

59. EXPOSE API USING
    MASHERY
    

    View Slide

60. ARCHITECTURE
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

67. DEVELOPERS PORTAL
    Work in
    Progress
    

    View Slide

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

    View Slide

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

    View Slide

70. ANALYZE
    

    View Slide

71. AUTOMATED API
    AVAILABILITY TESTING 
    WITH RUNSCOPE
    

    View Slide

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

    View Slide

73. CHANGES
    &
    VERSIONING
    

    View Slide

74. –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 Slide

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

    View Slide

76. 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 Slide

77. 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 Slide

78. 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 Slide

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

    View Slide

80. FULL PICTURE
    

    View Slide

81. AUTOMATED
    CONTRACT-DRIVEN API
    LIFECYCLE
    

    View Slide

82. 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 Slide

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

    View Slide

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

    View Slide

85. COMPLETE B2B
    HAPPENING 
    THROUGH APIS
    

    View Slide

86. DIGITAL 
    CREATION:
    CREATING 
    THE NEW
    

    View Slide

87. THANK YOU
    ZDENEK “Z” NEMEC
    OLDRICH NOVAK
    https://goodapi.co
    @zdne
    GOOD
    API
    oldrich.novak@adidas-group.com
    

    View Slide

88. Q&A
    ZDENEK “Z” NEMEC
    OLDRICH NOVAK
    https://goodapi.co
    @zdne
    GOOD
    API
    oldrich.novak@adidas-group.com
    

    View Slide

89. https://www.karliekloss.com
    

    View Slide