This talk describes the development of ABN AMRO’s API handbook, the single-source of truth for the development and management of internal and external API products. Our company is moving towards an API-First culture and mentality. Streamlining the development process is key to enabling this. In the beginning, API development knowledge was not documented or centralized in one location. Accurate information was not available for developer teams and they were not aware of what exactly the process entailed. My colleague and I began by making agreements on how the overall process works, describing it in an intuitive way, and then by making it open and accessible company-wide. This involved setting up and hosting face-to-face meetings or MS Teams calls with specialists to find out what was required This talk describes our approach to gathering content from experts, defining and refining processes, obtaining feedback from readers, and redesigning the content in a more user-centric format.

1. Blood, sweat, and creating an
API handbook
Brendan Lynch
API the Docs

2. • My journey
• ABN AMRO
• API First
• API handbook
 Process to create the API handbook
• Future improvements
Topics

3. My journey
Ireland
South Korea
The Netherlands

4. • A Dutch bank with headquarters in Amsterdam
• 3rd largest bank in the Netherlands
• Business lines:
• Personal banking
• Private banking
• Corporate & Institutional banking
• Mobile banking – Grip
• Open banking – Tikkie and FX Trade
ABN AMRO

5. API First

6. • Internal content which describes the API development process
• Multiple teams from different disciplines within the bank:
• Architects
• Internal and external gateway teams
• Standards, guidelines, and governance
• Marketing and promotion
• Internal development
• Security
• GOAL - Enable development teams to create APIs
API handbook
API
Handbook

7. Process to create the API Handbook
Agree on content
structure
1
2
3
4
5
Manage and review
author tasks
Refine processes
and structure
Test, release, and
obtain feedback
Agree on way
of working

8. • Set up meetings with all stakeholders
• Agree on a structure to group the content
• Original structure:
Design  Implement  Release  Manage
1. Agree on content structure

9. • Define the author/reviewer relationship
• Create task backlog
• Define and set up weekly API handbook meeting
• Create a set of writing standards:
• Technical Writing Style Guide
• Provide training on Technical Writing
2. Agree on way of working

10. • Keep track of task status
• Provide technical writer review
• Attend and chair weekly API handbook meeting
• Set time expectations
• Maintain task backlog
3. Manage and review author tasks

11. • Read out-loud tests
• Provide access to users (Release)
• Reach out to author teams
• Collect feedback from users
• Ensure content is up-to-date
4. Test, release, and obtain feedback

12. • Based on feedback, move to a process-oriented structure
• Create content architecture map
• Define the main processes:
• Create a new API
• Update a released API
• Retire an API
• Define and implement content reuse
• Specify and determine process owners
5. Refine processes and structure

13. • Move content from Confluence to Markdown
• Static site
• Reviews as Bitbucket pull requests
• Pipeline for publishing
• Create an integrations handbook that includes:
• REST APIs
• Batch
• Streaming
• Review and improve content regularly
Future improvements

14. ABN AMRO’s External API Developer Portal
https://developer.abnamro.com/

15. LinkedIn profile:
www.linkedin.com/in/brendan-lynch777/
Thank you!