The Path of Good API

10 things I learned about APIs in 7 years.

The deck used during my presentations at API Days Paris, January 2018

Transcript

1. THE PATH OF GOOD API
   Zdenek “Z” Nemec
   10 Things I Learned about APIs
   in
   7 Years
   goodapi.co
   

   View Slide

2. I help businesses to build their APIs
   Zdenek “Z” Nemec
   @zdne
   zdne1
   goodapi.co
   

   View Slide

3. https://goodapi.co
   INDEPENDENT API CONSULTING
   

   View Slide

4. THE PATH OF GOOD API
   No.10
   No.1 No.2 No.3
   No.4 No.5 No.6
   No.7 No.8 No.9
   goodapi.co
   Predom
   inant
   API Styles
   Digital
   Transform
   ation
   M
   anagem
   ent
   W
   ho
   Serves
   Custom
   ers
   Product
   Ow
   ner
   Challenges
   Architecture
   Tools
   are
   the
   lim
   its
   Data
   M
   odel
   Future
   

   View Slide

5. WORLD RUNS ON
   SOAP, EDI OR FTP
   goodapi.co
   No.1
   

   View Slide

6. – Pingdom Blog, October 2010
   “REST in Peace SOAP”
   goodapi.co
   

   View Slide

7. IN REALITY, MOST OF THE SERVICES
   YOU HAVE USED TO GET TO THIS
   CONFERENCE ARE UTILIZING SOME
   OTHER TYPES OF APIS BUT REST
   goodapi.co
   

   View Slide

8. This is the same rhetorics from REST evangelists
   towards SOAP as we see today from GraphQL
   towards REST
   goodapi.co
   

   View Slide

9. THERE WERE TWO
   WAVES OF API DIGITAL
   TRANSFORMATION
   goodapi.co
   No.2
   Two Groups of Customers
   

   View Slide

10. 1. LARGE ORGANIZATIONS
    EMBRACING IT
    2. UBIQUITOUS INTERNET AND
    SOFTWARE DEVELOPMENT
    goodapi.co
    

    View Slide

11. FIRST WAVE
    goodapi.co
    Fulfilled by SOAP, EDI, FTP, ESB, etc.
    

    View Slide

12. SECOND WAVE
    goodapi.co
    

    View Slide

13. TWO WAVES
    goodapi.co
    Two Groups of Customers
    CUSTOMER
    SPECIFIC
    APIS
    GENERIC
    APIS
    VS.
    many mid- or small size
    customers
    few large established
    customers
    

    View Slide

14. THE NEW (SECOND WAVE)
    TYPE OF CUSTOMERS IS
    IGNORED OR UNDERSERVED
    BY INCUMBENTS
    goodapi.co
    

    View Slide

15. YOU CAN CONVINCE
    MANAGEMENT ABOUT
    THE IMPORTANCE OF APIS
    No.3
    goodapi.co
    

    View Slide

16. IF YOU DON’T DO IT,
    SOMEBODY ELSE WILL
    SERVE YOUR CUSTOMERS
    No.4
    goodapi.co
    

    View Slide

17. Incumbent
    Existing
    Customer
    Existing
    Customer
    Existing
    Customer
    goodapi.co
    FIRST WAVE
    

    View Slide

18. Incumbent
    Existing
    Customer
    Existing
    Customer
    Existing
    Customer
    3rd party
    New Type
    of
    Customer
    ignored at the start
    Second
    Wave of
    Customers
    goodapi.co
    SECOND WAVE
    

    View Slide

19. Incumbent
    Existing
    Customer
    Existing
    Customer
    Existing
    Customer
    3rd party
    New Type
    of
    Customer
    New Type
    of
    Customer
    New Type
    of
    Customer
    goodapi.co
    SECOND WAVE
    

    View Slide

20. Incumbent
    Existing
    Customer
    Existing
    Customer
    Existing
    Customer
    3rd party
    New Type
    of
    Customer
    New Type
    of
    Customer
    New Type
    of
    Customer
    goodapi.co
    SECOND WAVE TAKING OVER
    FIRST WAVE CUSTOMERS
    

    View Slide

21. Existing
    Customer
    Existing
    Customer
    Existing
    Customer
    3rd party
    New Type
    of
    Customer
    New Type
    of
    Customer
    New Type
    of
    Customer
    goodapi.co
    Incumbent Incumbent Incumbent
    UNIFORM INTERFACE
    Uniform Interface
    

    View Slide

22. Website “Providers”
    Client Client Client Client Client Client
    goodapi.co
    ARE YOUR CUSTOMERS
    YOURS?
    

    View Slide

23. THE WAY OUT
    goodapi.co
    

    View Slide

24. API PRODUCT OWNER
    IS KEY TO SUCCESS
    No.5
    goodapi.co
    

    View Slide

25. YOU DON’T HAVE TO HAVE
    EXPENSIVE API PROGRAM, JUST GET
    SOMEBODY WHO CARES ABOUT
    YOUR APIS AND WILL BE
    RESPONSIBLE FOR THEM
    goodapi.co
    

    View Slide

26. API-FIRST IS STILL A
    MAJOR CHANGE FOR
    MANY COMPANIES
    goodapi.co
    

    View Slide

27. SOMETIMES YOU
    HAVE TO BOIL THE
    OCEAN
    No.6
    goodapi.co
    

    View Slide

28. INCUMBENTS
    HEAVILY INVESTED IN
    FIRST WAVE
    goodapi.co
    SOAP, EDI, FTP, ESB, “private clouds” but
    also processes and trained experts.
    

    View Slide

29. CUSTOMERS FROM THE
    FIRST WAVE OFTEN DO
    NOT UNDERSTAND THE
    SECOND WAVE
    goodapi.co
    

    View Slide

30. HOT POTATOES
    • API First, product owner present
    • Generation of API documentation from code
    • Building your own platform (cloud vs. own infrastructure)
    • Abuse of HTTP because first-wave customers “don’t get
    it”
    • Hypermedia
    • Versioning
    • Applying existing architecture and styles
    goodapi.co
    

    View Slide

31. OFTEN, A WRONG
    API STYLE IS USED
    The Right Architectural Style
    No.7
    goodapi.co
    

    View Slide

32. PICK THE RIGHT
    ARCHITECTURAL
    STYLE
    Don’t jump on REST or GraphQL just because its #trending
    sometimes, sending a file is the right way to go
    goodapi.co
    

    View Slide

33. SIMPLICITY, TRENDS AND SPEED
    TODAY
    WINS
    OVER
    LONGEVITY AND SPEED TOMORROW
    goodapi.co
    

    View Slide

34. PREVENT
    UNINFORMED
    DECISIONS
    goodapi.co
    

    View Slide

35. TOOLS ARE OUR
    LIMITS
    No.8
    goodapi.co
    

    View Slide

36. TOOLS ARE OUR LIMITS
    • Existing investments (tools, infrastructure & processes)
    • Bloated API Management Tools
    • Limiting API description formats
    • Data modeling from the past
    • Tooling for structured data
    goodapi.co
    

    View Slide

37. CANONICAL DATA
    MODEL DOESN’T
    WORK
    No.9
    goodapi.co
    

    View Slide

38. CANONICAL DATA MODEL IS
    ANTI PATTERN IN
    MICROSERVICES AND FAAS
    WORLD
    goodapi.co
    Use concern separation, bounded context,
    DDD techniques
    

    View Slide

39. UNIFORM INTERFACE
    IS THE FUTURE
    No.10
    goodapi.co
    

    View Slide

40. goodapi.co
    ENGINEERING PRINCIPLE OF
    GENERALITY
    1957 2017
    

    View Slide

41. A CONSISTENT, PREDICTABLE
    WAY TO QUERY DATA AND
    EXERCISE ACTIONS REGARDLESS
    OF THE APPLICATION DOMAIN
    AND PROVIDER
    goodapi.co
    

    View Slide

42. WHY IS UI THE FUTURE?
    • Simplifies architecture
    • Improves visibility of interactions
    • Decouple components, enables evolution
    • Improves interoperability, reduces cost of integration
    • Reduces costs and time to market
    • Enables autonomous service discovery
    • ENABLES FOR GENERAL AI
    • Automatic clients
    • Autonomous clients
    goodapi.co
    

    View Slide

43. UNIVERSE OF CAPABILITIES
    goodapi.co
    

    View Slide

44. This is what Amazon (Alexa skills), Google
    (Home skills) & VIV are doing...
    DATABASE OF KNOWLEDGE AND
    SERVICES WITH UNIFORM INTERFACE
    goodapi.co
    

    View Slide

45. PATH TO UI
    • Platforms like StdLib / Algorithmia
    • Architectural Styles (REST, GraphQL)
    • Structured Data (JSON-LD)
    • AI Databases (Grakn.ai)
    • Or we leave it up to Amazon and Google to become the
    3rd party, intermediaries, to the universe.
    goodapi.co
    

    View Slide

46. Do you want to provide a uniform interface or
    leave it to third-party vendors to do it?
    goodapi.co
    BUILDING YOUR NEXT
    API
    Client Client Client Client Client
    Provider Provider
    Client Client
    Structured Data & Architecural Style
    Client Client Client
    Provider Provider Provider
    - OR -
    

    View Slide

47. GOOD
    API
    Independent API Consulting
    https://goodapi.co
    

    View Slide