Guide to writing API requirements as a

Business Analyst

Diwakar Singh
Writing API (Application Programming Interface) requirements involves
specifying the methods, expected inputs and outputs, error handling,
and security aspects of an API. These requirements serve as a contract
between the developers who build the API and the stakeholders who
use it or integrate with it.

Here's a step-by-step guide followed by a detailed example:

Steps to Write API Requirements

Purpose Description: Clearly define the purpose of the API. What

functionality does it provide? Who are its intended users?

Endpoint Definitions: Specify the endpoints of the API, describing what

each endpoint does.

Request and Response Formats: Define what data formats will be used
(e.g., JSON, XML) and detail the structure of the request and response
bodies.

HTTP Methods: Specify which HTTP methods (GET, POST, PUT, DELETE,
etc.) will be used for each endpoint.

Parameters and Serialization: Detail any parameters required by each

endpoint, including path, query, and body parameters. Specify how
data should be serialized.

Authentication and Authorization: Describe how the API will secure

requests, such as tokens or API keys, and what permissions are needed
to access different parts of the API.

Error Handling: Define common error responses and status codes to

ensure consistency and ease of use.
Rate Limiting and Quotas: Specify any limitations on how often the API
can be called.

Versioning: Outline the strategy for versioning the API to handle future
changes without disrupting existing users.

Examples: Include examples of requests and responses to clarify

expected interactions with the API.

Detailed Example: Customer Management API

Purpose

The Customer Management API allows client applications to manage

customer information within a retail management system. It supports
operations for creating, retrieving, updating, and deleting customer
details.

Endpoints

Create Customer:
Endpoint: /api/customers
Method: POST
Request Body: { "firstName": "string", "lastName": "string", "email":
"string", "phoneNumber": "string" }
Response: { "customerId": "string", "firstName": "string", "lastName":
"string", "email": "string", "phoneNumber": "string", "createdAt":
"timestamp" }
Status Codes:
 • 201 Created: Successfully created customer.
• 400 Bad Request: Missing or invalid fields in request body.
• 500 Internal Server Error: Server error during processing.

Get Customer:
Endpoint: /api/customers/{customerId}
Method: GET
Response: { "customerId": "string", "firstName": "string", "lastName":
"string", "email": "string", "phoneNumber": "string", "createdAt":
"timestamp" }
Status Codes:
• 200 OK: Successfully retrieved customer.
• 404 Not Found: Customer ID does not exist.
• 500 Internal Server Error: Server error during processing.

Authentication

• Method: OAuth 2.0 token authentication.

• Scopes:
o [Link]: Required to retrieve customer details.
o [Link]: Required to create, update, or delete
customer details.

Error Handling

• Format: { "error": "string", "message": "string", "status":

"number" }
Rate Limiting
• Limit: 1000 API calls per hour per client.

Versioning
• Current Version: v1
• Strategy: URL versioning (e.g., /api/v1/customers)

User Story: Create Customer

As a client application,

I want to be able to send a POST request to create a new customer,

So that the customer's information can be stored in the retail

management system.

Acceptance Criteria

1. Successful Creation:
o Given valid customer data,
o When a POST request is made to /api/customers,
o Then the API should return a 201 status code and a JSON
response including all customer fields with a generated
customerId and createdAt timestamp.
2. Handling Missing or Invalid Fields:
o Given incomplete or invalid customer data,
o When a POST request is made to /api/customers,
o Then the API should return a 400 status code and an error
message detailing what was missing or invalid.
3. Server Error:
 o Given a server-side error during the creation process,
o When a POST request is made to /api/customers,
o Then the API should return a 500 status code and an error
message indicating a server error.

User Story: Retrieve Customer

As a client application,

I want to be able to send a GET request to retrieve a customer’s details,

So that I can display or use the customer's information in my

application.

Acceptance Criteria

4. Successful Retrieval:
o Given an existing customerId,
o When a GET request is made to
/api/customers/{customerId},
o Then the API should return a 200 status code and a JSON
response containing all the customer's details.
5. Customer Not Found:
o Given a non-existent customerId,
o When a GET request is made to
/api/customers/{customerId},
o Then the API should return a 404 status code and an error
message indicating the customer was not found.
6. Server Error:
o Given a server-side error during the retrieval process,
o When a GET request is made to
/api/customers/{customerId},
 o Then the API should return a 500 status code and an error
message indicating a server error.

General Acceptance Criteria for All API Operations

• Authentication: Every request must include a valid OAuth 2.0

token. If a request lacks a valid token or the token does not have
the necessary scopes ([Link] for GET, [Link] for
POST, PUT, DELETE), the API should return a 401 Unauthorized
status code.
• Rate Limiting: The API should not allow more than 1000 calls per
hour from a single client application. If this limit is exceeded,
return a 429 Too Many Requests status code with an appropriate
error message.
• API Versioning: Requests must be made to the correct version of
the API (e.g., /api/v1/customers). If an incorrect or deprecated
version is requested, return a 410 Gone status code with an
appropriate error message.

Functional Requirements

Functional requirements define specific behaviors or functions of the

API:

Create Customer:

The API must allow the creation of a customer record via a POST
request.
The request must include customer data such as first name, last name,
email, and phone number.
The response must include the newly created customer ID and creation
timestamp.

Retrieve Customer:

The API must allow the retrieval of a customer’s details via a GET
request using a customer ID.
The response must include all details of the customer if found.
If no customer is found, the API must return an appropriate error
message.

Update Customer (Assumed requirement for completeness):

The API should allow the updating of an existing customer's details via a
PUT request.
The request must specify the customer ID and data to update.
The response should confirm the updated details.

Delete Customer (Assumed requirement for completeness):

The API should allow the deletion of a customer record via a DELETE
request using a customer ID.
The response should confirm that the customer has been deleted.

Error Handling:

The API must handle and return appropriate errors for invalid requests
(e.g., bad request, unauthorized access, not found, method not
allowed, server errors).

Data Validation:

The API must validate input data for correctness and completeness
before processing.
Non-Functional Requirements

Non-functional requirements specify the overall standards and

characteristics of the API:

Security:

The API must implement OAuth 2.0 for authentication and

authorization.
Sensitive data should be encrypted during transit using TLS.

Performance:

The API should handle a minimum of 1000 requests per hour from a
single client.
The response time for fetching customer details should not exceed 2
seconds under normal conditions.

Scalability:

The API should be able to handle an increase in load without significant

degradation of performance.

Availability:

The API should be available 99.9% of the time.

Maintainability:

The API should be designed for easy maintenance, updates, and

troubleshooting.
Proper logging should be implemented for critical processes.

Rate Limiting:
The API should enforce rate limiting to prevent abuse and ensure fair
usage — 1000 API calls per hour per client.

Versioning:

The API must support versioning and allow backward compatibility for
existing clients.

Documentation:

Comprehensive documentation must be provided, including detailed

endpoint descriptions, request/response formats, examples, and error
codes.

Compliance and Standards:

The API design and implementation should comply with relevant

industry standards and legal regulations regarding data handling and
privacy.