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

Effective API Governance: Lessons Learnt

Effective API Governance: Lessons Learnt

Talk delivered at API the Docs Amsterdam 2019

Alvaro Navarro

October 10, 2019
Tweet

More Decks by Alvaro Navarro

Other Decks in Programming

Transcript

  1. © 2016 Amadeus IT Group and its affiliates and subsidiaries
    Effective API Governance
    Lessons Learnt
    Alvaro Navarro
    Amsterdam, 10th October 2019

    View full-size slide

  2. Once upon a time

    View full-size slide

  3. Trip Purpose Prediction API
    Once upon a time

    View full-size slide

  4. Once upon a time
    Returns the forecast purpose of a trip Business
    or Leisure based on a search criteria.

    View full-size slide

  5. GET /flights/predictions/purpose
    Once upon a time

    View full-size slide

  6. origin : MAD
    destination : AMS
    departure : 20191012
    return : 20191015
    Once upon a time

    View full-size slide

  7. {
    "result": {
    "prediction" : "BUSINESS",
    "probability": 0.751
    }
    }
    Once upon a time

    View full-size slide

  8. Accept: application/vnd.amadeus.v1.full+json
    Once upon a time

    View full-size slide

  9. Once upon a time

    View full-size slide

  10. You need your API validated by the API
    Governance Board!
    Once upon a time

    View full-size slide

  11. Once upon a time

    View full-size slide

  12. Once upon a time

    View full-size slide

  13. Once upon a time

    View full-size slide

  14. Once upon a time

    View full-size slide

  15. Once upon a time

    View full-size slide

  16. Hello World
    @alnacle

    View full-size slide

  17. Motivation
    More than 20 years working with APIs
    ○ EDIFACT
    ○ SOAP/XML
    ○ REST/JSON
    ○ Protobuf
    ○ GraphQL

    View full-size slide

  18. Motivation
    Many people designing and implementing APIs

    View full-size slide

  19. Motivation
    Difficult to reuse across backends

    View full-size slide

  20. Motivation
    We need to regulate this!

    View full-size slide

  21. What is the API
    Governance?

    View full-size slide

  22. What is the API Governance?
    Community of API Designers and Developers

    View full-size slide

  23. What is the API Governance?
    Owners of guidelines, data dictionaries and
    processes

    View full-size slide

  24. What is the API Governance?
    Support

    View full-size slide

  25. In Amadeus we
    introduced the HAPPY
    principle

    View full-size slide

  26. What is the API Governance?
    Homogeneous

    View full-size slide

  27. What is the API Governance?
    Homogeneous
    Active

    View full-size slide

  28. What is the API Governance?
    Homogeneous
    Active
    Pragmatic

    View full-size slide

  29. What is the API Governance?
    Homogeneous
    Active
    Pragmatic
    Positive

    View full-size slide

  30. What is the API Governance?
    Homogeneous
    Active
    Pragmatic
    Positive
    Young

    View full-size slide

  31. Why API
    Governance?

    View full-size slide

  32. Why API Governance?
    As API Producer

    View full-size slide

  33. Why API Governance?
    Design Guidelines and Standardization

    View full-size slide

  34. Why API Governance?
    Design Guidelines and Standardization
    ❏ Errors
    ❏ Endpoint/parameters naming
    ❏ Improvements
    ❏ Data Dictionaries
    ❏ Versioning

    View full-size slide

  35. Why API Governance?
    Using URLs
    http://api.amadeus.com/v1/flight-search
    http://api.amadeus.com/2018/flight-search
    http://api.amadeus.com/2018/02/flight-search
    Using HTTP Header
    Accept: application/vnd.amadeus.v1 Accept-Version: 1
    Using a Query parameter
    $ curl http://api.amadeus.com/flight-search?version=1

    View full-size slide

  36. Why API Governance?
    As API Consumer

    View full-size slide

  37. Why API Governance?
    Better API integration and consistency

    View full-size slide

  38. Why API Governance?
    import amadeus
    client = amadeus.Client()
    response = client.shopping.flight_destinations.get(origin = 'AMS',
    maxPrice = '500')

    View full-size slide

  39. How do we make
    it work?

    View full-size slide

  40. How do we make it work?
    Technical discussions: Decision Logs

    View full-size slide

  41. How do we make it work?
    API submissions: Review Cards

    View full-size slide

  42. How do we make it work?

    View full-size slide

  43. How do we make it work?
    Under Construction In Progress Pending Validated
    Review Process ( 1 week )
    1 to 4 weeks
    ❏ Validated Review Card
    ❏ Documentation
    ❏ Swagger
    Designer

    View full-size slide

  44. Lessons Learnt

    View full-size slide

  45. Lessons Learnt
    Tools are your friends!
    ○ Designing
    ○ Documenting
    ○ Testing

    View full-size slide

  46. Lessons Learnt
    Be an advocate and spread the word!

    View full-size slide

  47. Lessons Learnt
    It's not a control entity !
    Democratic approach when designing APIs

    View full-size slide

  48. Lessons Learnt
    It is a place to speak and share knowledge

    View full-size slide

  49. Thanks!
    developers.amadeus.com

    View full-size slide