The document discusses lessons learned from building enterprise APIs, highlighting the importance of API management, monitoring, and using metadata for communication between systems. It emphasizes the need to simplify and select relevant technologies while preparing for the inevitability of legacy systems over time. Additionally, the document suggests strategies for handling legacy APIs through converters and adapters and stresses the importance of robust logging and user-centric design.

1. Lessons learned from
building enterprise APIs
Gustaf Nyman
Apitek Aktiebolag
gustaf.nyman@apitek.se
as presented at the Nordic APIs 2016 Platform Summit

2. About Enterprise APIs
Enterprises have:
• In-house developed systems
• Acquired system
• External SaaS
• Clients as mobiles, tablets etc.
Most systems communicate and expose APIs
Enterprises has many internal APIs
Enterprises has legacy* APIs using old technology

3. You need API management
Single point API gateway:
• Route message to backend service
• Sometimes convert or translate messages
• Necessary if using microservice architecture
Administration:
• Keep track of routing configuration and metadata
Monitoring:
• Does it work? If not why?
• Is it fast enough?
Miscellaneous:
• Authentication, throttling, signing, validation, archiving etc.

4. API gateway
Internal API client Internal API server
External API serverExternal API client
API gateway
Internet
Intranet
Cloud vnet

5. API gateway
Routing of messages to back-end services
Protocol translation - to support legacy APIs
Keep track of all routing info and metadata
• WSDL/XML Schema, Swagger/JSON Schema etc.
Logging, monitoring and analytics:
• Simplifies monitoring and debugging of connected systems
Performance and reliability
Admin tool
The natural choice for developers and others

6. Real world: Using legacy API
Task 2002: Access legacy API (monolith) using modern tech?
Legacy API:
• Queue based transport
• Text based message format (structure and value)
• 70 message types

7. Solution legacy API
Use XML, XML Schema, SOAP and WSDL.
Convert between XML and legacy format using XML Schema
Generate WSDL/XML Schema from repository

8. API client Legacy API server
XML Schema driven converter
XML
Schema
{getspeakerNordic APIsLesson learned}
<getspeaker>
<conference>Nordic APIs<conference>
<presentation>Lesson learned</presentation>
</getspeaker>
XML Schema
driven converter
Queue adapter
SOAP/HTTP Text/Queue

9. API gateway
Internal API client
Legacy API server
External API serverExternal API client
API Gateway
Internet
Intranet
Converter

10. Real World: Using legacy API
Task 2015: Access legacy API using modern tech?
Legacy API:
• SOAP/HTTP based transport
• XML message format described in WSDL/XML Schema
Move to modern technology, Microservices?

11. Solution: legacy API
Use JSON and Swagger/JSON Schema.
Convert between XML and JSON using existing XML Schema
Generate Swagger from WSDL using mapping rules

12. Lesson: Use metadata
Description of data, message exchange and contracts:
• WSDL/XML schema and Swagger/JSON schema
Use of metadata:
• Validate data and message exchange
• Generate stubs for client and server code
• Generate documentation, test data, user interfaces
• Data format conversion – with certain constraints
But remember:
• API/contract needs to be the first thing you design
• Think before generating from code or tools
• Make sure schemas are comprehensible!

13. Real World: B2B communication
Swedish insurance business 2002:
• Documents on paper communicated through surface mail.
Task: Define B2B communication guidelines, a ”standard”
Business requirements:
• Non repudiation
• Confidentiality
• Simple to implement on any platform/language

14. Solution: SOAP/WS-Security
Use standards, but define how and simplify:
• SOAP/HTTPS and WSDL/XML Schema
• X509 certificates and WS-Security for signing
• X509 client certificates
Add what’s missing:
• Organization identification header and correlation id
• A few standardized message types
10 years later still the natural B2B choice in the Swedish insurance
business.

15. Lesson: Simplify and select
If you want things to last..
• Do not use ”everything” technologies provide – select the good
stuff!
• Read the specifications – do not rely only on ready-made
toolkits or frameworks.
• Remember: Simple things are easier to migrate and adapt to
new technology

16. Problem: API failures
All APIs will eventually fail…
Ongoing task: improve analysis and production debugging support

17. Monitor and log
Log types:
• Processing logs – what happened?
• Data logs – what was the message content at specific point?
• Analytics logs – what is the response times and failure rate?
Logging subsystem:
• Should be always on
• Must be high performance and
• Must handle large amount of logs
• Must correlate and cluster related log data

18. What to log?
“Logga lagom”, i.e. log just enough information
• Too much and it becomes incomprehensible and unmanageable
• Too little and it is useless
Use experience and an evolutionary approach:
• You debug a difficult problem – improve log to enable easy
identification next time
• Always strive to enable less experienced personnel to effectively
debug using logs

19. Real world: Logging subsystem
Always on log system logs to disk – remove after 24 hours
On API failure related log files are stored in database
Web site to:
• Access and view error log data
• Automatic classification of errors using patterns
• Searching and reading logs on disk
• View other logs and system parameters

20. Take care of all your users
Your platform should be the natural choice for developers
• Cater to their needs.
More than developers:
• Many more are interested in what you are doing
• Many users are not computer savvy – they need simple tools
Typical non-technical users:
• People responsible for the business
• Testers with extensive business skills
• Customer service

21. Problem: Old technology
If we only redesign our system with…
• RPC
• CORBA/MTS
• SOAP/SOA
• REST/HTTP
• Event driven
• Microservices
• [your choice of the next big thing]
We will solve all problems and everything will be much better…

22. Everything will be legacy
…It is just a matter of time.
If redesign is not an option, put legacy APIs behind converters,
translators and adapters:
• Expose the modern API you prefer
Be prepared…
• Use standards – avoid vendor specific extensions
• Be selective – do not use everything
• Simplify
…mitigate the consequences of systems turning legacy

23. Summary
Use an API gateway
Use metadata
Simplify and select
Monitor and log
Prepare for systems turning legacy
gustaf.nyman@apitek.se
https://www.apitek.se/
Do not miss my talk tomorrow 14.15:
Build, Deploy and Test APIs and Microservices with Apitek Prisma