The Business Analyst’s Guide to Understanding
APIs
By Amreen Usmani
This guide is for Business Analysts who work closely with development teams but want a clearer
understanding of how APIs work, how to read API documentation, and how to define and
communicate API-related requirements effectively. You don’t need to be technical — just curious.
Chapter 1: What Is an API?
An API (Application Programming Interface) allows software systems to talk to each other. It acts
like a contract between two applications. You send a request to the API, and it sends back a
response.
■ Real-World Analogy:
Imagine a restaurant. You (the customer) place an order through a waiter (the API). The kitchen
(server) prepares your food and the waiter brings it back to you. You don’t go into the kitchen — you
just interact through the waiter.
Chapter 2: Understanding Requests and Responses
An API typically works over HTTP and follows a request-response pattern. A client sends a request
to a server, and the server responds with data.
Method Purpose Example
GET Retrieve data GET /users/123
POST Create data POST /users
PUT Update data PUT /users/123
DELETE Remove data DELETE /users/123
Chapter 3: Anatomy of an API Request
■ **Endpoint** – The URL of the API (e.g., [Link]
■ **Headers** – Metadata, often including authentication tokens.
■ **Payload** – The body of data sent (used in POST/PUT requests).
■ **Query Parameters** – Extra filters passed in the URL (e.g., ?sort=desc).
Chapter 4: Anatomy of an API Response
Most APIs respond with JSON (JavaScript Object Notation) — a lightweight data format that's easy
to read.
■ Example JSON Response:
{ "id": 123, "name": "Amreen", "email": "amreen@[Link]" }
Chapter 5: How BAs Can Read API Documentation
• Know where to find the base URL and version.
• Identify the available endpoints.
• Understand required parameters and authentication needs.
• Look for sample requests/responses and error codes.
Chapter 6: Writing API Requirements as User Stories
■ Example User Story:
As a registered user, I want to retrieve my profile details via the API so that I can view my
information in the app.
■ Acceptance Criteria (Gherkin style):
Given the user is authenticated When they call the GET /users/123 endpoint Then the API should
return the user’s details in JSON format
Chapter 7: Common Pitfalls & Developer Collaboration Tips
■ Common Pitfalls:
• Not asking about required parameters.
• Ignoring HTTP status codes (e.g., 200 OK vs 404 Not Found).
• Assuming frontend and backend are always in sync.
• Not involving devs when defining API behavior.
■ Collaboration Tips:
• Ask devs to walk you through sample responses.
• Use tools like Postman to test endpoints hands-on.
• Create mock API definitions for early alignment.
• Clarify edge cases with examples in your user stories.
Final Thoughts
Understanding APIs is quickly becoming a must-have skill for Business Analysts in every industry
— not just tech. With this guide, you're better equipped to participate in API-driven discussions,
collaborate more effectively with your dev team, and confidently document integration
requirements.
Keep learning. Stay curious. Grow with tech. ■
– Amreen Usmani