API & System Integration Analysis for BA/SA

Section 1: Integration in the Organisation

• Why so many projects are delayed at the integration points
• Main patterns: REST API, SOAP, file batch (SFTP), webhook, message queue and database link
• Synchronous versus asynchronous integration and the effect on user experience
• Point-to-point versus using an API gateway or integration platform
• The role of the BA/SA in integration projects and the documents they deliver
• Workshop: compare integration patterns to choose the right one for a business need

Section 2: HTTP and REST Basics Every BA/SA Needs

• Request and response structure: URL, method, headers and body
• HTTP methods and what each one means for the business
• Status codes in the 2xx, 4xx and 5xx ranges and their effect on system design
• JSON and XML data formats, reading nested structures and arrays
• Resources, endpoints, path parameters, query parameters and pagination

Section 3: Lab: Testing APIs with Bruno

• Install and set up collections, environments and variables
• Send GET, POST, PUT and DELETE requests and read results and status codes systematically
• Add headers for authentication and handle tokens
• Record test results as evidence for the requirements document
• Standard questions to ask the API owner before starting any design

Section 4: Reading API Specifications

• The structure of OpenAPI 3.1 and viewing it in Swagger Editor
• Reading schemas, required fields, enums and examples
• How to check whether the documentation received is complete enough to design from
• A checklist for assessing the quality of API documentation from partners
• Lab: read an OpenAPI document and summarise what the target system does and does not support

Section 5: Workshop Day 1: Exploring the NovaRetail Payment API

• Play the SA at NovaRetail, connecting a new sales system to an external payment provider
• Test the simulated payment API with Bruno for both normal and invalid data
• Summarise behaviour, limitations and questions for the system owner in a standard form
• Share findings with the group to prepare for writing requirements on day two

Section 6: Designing the API Contract

• What a good contract contains: endpoint, method, request, response, errors and business rules
• Field specification: data type, length, date format, allowed values and mandatory fields
• Naming fields and endpoints consistently across the organisation
• API versioning and the impact when a partner changes version
• Contract first, so that teams on both sides can develop in parallel
• Lab: write request and response schemas with mandatory fields, data types and date formats

Section 7: Explaining the Flow with Diagrams

• Sequence diagrams for processes that involve several systems
• Data flow diagrams to show data paths and transformations
• Drawing diagrams with Mermaid so they can be embedded in documents and version-controlled
• Using diagrams in partner meetings to reduce misunderstandings
• Lab: draw a sequence diagram of the flow between three systems

Section 8: Designing Error Handling, Timeouts and Retries

• Error matrix: error codes, business meaning, user-facing messages and system actions
• Timeout and retry policy: number of attempts, intervals and exponential backoff
• Lab: design an error matrix for the simulated payment integration with the action for each case

Section 9: Idempotency, Reconciliation and Monitoring

• Idempotency: why resending creates duplicate transactions and how to design an idempotency key
• Handling pending transactions and uncertain states
• Daily reconciliation between source and target systems
• Alerts and monitoring so the team learns about problems before customers do
• Lab: define retry, timeout and idempotency key rules to prevent duplicates, and design the reconciliation process

Section 10: API Security at the Level a BA/SA Needs

• Authentication: API key, Basic Auth, OAuth 2.0 and JWT, their differences and use cases
• Authorisation and role-based permissions
• Rate limiting and throttling and their effect on batch job design
• Encryption in transit and data signing for financial transactions
• PDPA considerations: which data must not be sent through an API or written to logs

Section 11: Non-functional Requirements

• Peak transaction volume, acceptable response time and service hours
• SLAs with external providers and what the contract must state
• Logging and audit trail requirements for later review

Section 12: Test Planning and Handover

• Mock the target system with Mockoon to test before the real system is ready
• Design integration test cases covering the happy path, error paths and edge cases
• Define measurable acceptance criteria
• Go-live checklist: environments, credentials, firewall and fallback plan
• Lab: build a mock API in Mockoon that simulates both success and failure cases

Section 13: Master Workshop: NovaRetail Integration Requirements

• Write API contracts for all three systems: payment, accounting and customer notification
• Assemble the sequence diagram, error matrix, and retry and idempotency policy
• Design the reconciliation process and integration test cases with acceptance criteria
• Present the integration requirement document to the group for feedback
• Review API documents from learners' own projects together (if available)