🔰 Stage 1: Foundation – Understand the Basics
As a BA, you don’t need to code APIs, but you must understand what they are, how they work, and why they matter.
Key Concepts:
- What is an API?
- A set of rules that allow applications to communicate.
- Types of APIs:
- REST, SOAP, GraphQL, Webhooks
- JSON vs. XML
- HTTP methods: GET, POST, PUT, DELETE
- API request/response structure
- Status codes: 200 (OK), 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
Learning Tools:
- Postman (for API testing)
- Swagger / OpenAPI documentation
🔧 Stage 2: API Use in Business Context
Focus on how APIs solve business problems and support integration and automation.
BA Responsibilities:
- Identify business needs that require system integration
- Capture functional and non-functional requirements involving APIs
- Work with developers to specify data inputs/outputs
- Validate that APIs align with business rules
Deliverables:
- API requirements in user stories:
“As a user, I want to retrieve my order history so that I can track my purchases.”
- Interface specifications (including endpoints and parameters)
- Use cases or sequence diagrams showing API interactions
🧭 Stage 3: Working with API Documentation
Learn how to read and interpret API documentation, such as:
Key Items:
- Base URL (e.g.
https://api.example.com/v1)
- Endpoints (e.g.
/users, /orders)
- Authentication methods (API key, OAuth2)
- Rate limits and error handling
- Field definitions and data types
Tools:
- Swagger UI
- Postman examples
- API sandboxes/test environments
📊 Stage 4: API Modelling & Requirements Specification
Help define and document how APIs should behave from a business perspective.
Techniques:
- Use case diagrams or sequence diagrams showing system-to-system interactions
- Data flow diagrams (DFD) involving API systems
- Interface control documents (ICD) or API requirement specs
Example Requirements:
- Endpoint names and data to be exchanged
- Authentication needs
- Frequency of calls or polling
- Data validation rules
🔄 Stage 5: Agile, APIs & Continuous Delivery
Understand how APIs fit into Agile, DevOps, and CI/CD workflows.
What to Know:
- Writing API-related user stories and acceptance criteria
- Collaborating with Product Owners and Dev teams on API backlog
- Participating in API versioning and change impact analysis
- Testing support (using tools like Swagger, Postman)
🚀 Bonus: Tools & Skills to Explore
| Tool/Skill | Why It’s Useful |
|---|
| Postman | API testing, mock servers |
| Swagger (OpenAPI) | Reading and defining API contracts |
| JSON formatting | Understanding data exchange |
| JIRA/Confluence | Capturing and tracking API requirements |
| Microsoft Visio / Draw.io | Modeling API flows visually |
| Curl or browser dev tools | API response inspection |
✅ Summary: Business Analyst API Roadmap
| Level | Focus |
|---|
| 1. Fundamentals | Understand what APIs are and how they work |
| 2. Business Integration | Define business needs and requirements |
| 3. Documentation & Reading APIs | Interpret and validate API specs |
| 4. Requirements Modelling | Define data, flows, and system boundaries |
| 5. Agile & DevOps | Work with APIs in iterative development |
📄 API Requirements Document Template
1. API Overview
| Field | Description |
|---|
| API Name | User Profile API |
| API Purpose | To allow client applications to retrieve and update user profile information |
| Primary Use Case(s) | Fetch user data for display, update user profile from mobile app |
| Business Owner | Customer Service Department |
| Stakeholders | Product Owner, Dev Team, QA, End Users |
2. Business Requirements
| Requirement ID | Description |
|---|
| BR-01 | The system must allow users to retrieve their profile information using their user ID |
| BR-02 | The system must allow users to update their profile picture and personal details |
3. API Endpoint Details
| Method | Endpoint | Description |
|---|
| GET | /users/{id} | Fetch user profile by ID |
| PUT | /users/{id} | Update user profile details |
| POST | /users/{id}/photo | Upload user profile photo |
4. Request Parameters
| Name | Type | Required | Description |
|---|
id | string (UUID) | Yes | Unique identifier for the user |
email | string | No | Email address |
name | string | No | Full name |
photo | binary | No | Profile picture |
5. Response Schema
Success (200 OK):
jsonCopyEdit{
"id": "1234-5678",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"photo_url": "https://cdn.example.com/photos/jane.jpg"
}
Error (404 Not Found):
jsonCopyEdit{
"error": "User not found"
}
6. Authentication & Authorization
| Requirement | Details |
|---|
| Auth Method | OAuth2 Token |
| Role-based Access | Only users with profile:read or profile:write scope can access |
| Rate Limiting | Max 1000 calls/hour/user |
7. Validation Rules
| Field | Rule |
|---|
email | Must be a valid email format |
name | Must be at least 2 characters |
photo | Max file size: 2MB; Allowed types: JPG, PNG |
8. Non-Functional Requirements
| Type | Detail |
|---|
| Performance | API must return a response within 500ms |
| Availability | 99.9% uptime SLA |
| Scalability | Handle up to 10,000 concurrent requests |
9. Dependencies & Integration
| System | Interaction |
|---|
| CRM System | To sync updated user details |
| S3 Bucket | For storing profile photos |
| Auth Service | For validating tokens |
10. Test Scenarios
| Scenario | Description |
|---|
| TC-01 | Verify GET /users/{id} returns correct user data |
| TC-02 | Verify PUT /users/{id} updates only allowed fields |
| TC-03 | Verify error response for invalid token |
11. Change History
| Date | Change | Author |
|---|
| 2025-05-15 | Initial draft | Business Analyst |
12.Sequence diagram example
