Have you ever wondered how big companies deal with large amount of APIs? How do they keep consistency among the catalogue? Either if you are already running an internal API governance or you are thinking about start a new one, this talk will share our do’s and don’ts with the rest of the community.

1. ©2016AmadeusITGroupanditsaffiliatesandsubsidiaries
Effective API Governance
Lessons Learnt
Alvaro Navarro
Amsterdam, 10th October 2019

2. Once upon a time

3. Trip Purpose Prediction API
Once upon a time

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

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

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

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

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

9. Once upon a time

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

11. Once upon a time

12. Once upon a time

13. Once upon a time

14. Once upon a time

15. Once upon a time

16. Hello World
@alnacle

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

18. Motivation
Many people designing and implementing APIs

19. Motivation
Difficult to reuse across backends

20. Motivation
We need to regulate this!

21. What is the API
Governance?

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

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

24. What is the API Governance?
Support

25. In Amadeus we
introduced the HAPPY
principle

26. What is the API Governance?
Homogeneous

27. What is the API Governance?
Homogeneous
Active

28. What is the API Governance?
Homogeneous
Active
Pragmatic

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

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

31. Why API
Governance?

32. Why API Governance?
As API Producer

33. Why API Governance?
Design Guidelines and Standardization

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

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

36. Why API Governance?
As API Consumer

37. Why API Governance?
Better API integration and consistency

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

39. How do we make
it work?

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

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

42. How do we make it work?

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

44. Lessons Learnt

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

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

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

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

49. Thanks!
developers.amadeus.com