An API can be technically excellent and still create problems for the developers who need to use it.
Imagine an IBM i development team has successfully exposed customer, inventory, pricing, and order-processing functions through REST APIs.
The endpoints work. The RPG business logic is reliable. Connected applications can exchange information.
But six months later, another developer needs to use one of those APIs.
They discover that nobody documented the required parameters, error responses, authentication requirements, or business rules.
What should be a straightforward integration becomes a time-consuming investigation.
This is why IBM i API documentation should be treated as an essential part of modernization rather than an optional development task.
As organizations connect IBM i with cloud applications, customer portals, mobile devices, automation platforms, and AI systems, clear API documentation helps make those integrations easier to understand, reuse, test, and maintain.
Here are eight best practices IBM i teams can use to improve API documentation while preserving the RPG applications that continue to run critical business processes.
What Is IBM i API Documentation?
IBM i API documentation describes how external applications and developers can interact with business functions exposed through IBM i.
It explains what an API does, how to call it, what information it expects, and how it responds.
Effective documentation typically includes:
- API purpose and business context
- Endpoint URLs
- Supported HTTP methods
- Authentication requirements
- Required and optional parameters
- Request and response examples
- JSON or XML data structures
- Error codes and messages
- Business rules
- Version information
- API ownership and support contacts
The goal is to make an integration understandable without requiring every developer to examine the underlying RPG source code.
This becomes particularly important when IBM i capabilities are consumed by developers working with JavaScript, Python, Java, .NET, or cloud applications.
Why IBM i API Documentation Matters
IBM i applications often contain decades of business logic.
That logic may control:
- Customer-specific pricing
- Inventory availability
- Credit limits
- Order processing
- Shipping calculations
- Manufacturing operations
- Financial transactions
When these functions become accessible through APIs, the consuming application needs to understand how to use them correctly.
For example, a pricing API may require a customer identifier, product number, quantity, and transaction date.
If those requirements are not documented, developers may submit incomplete requests or misinterpret the results.
Good documentation reduces uncertainty.
It also helps organizations avoid unnecessary dependencies on individual developers who originally created the integration.
1. Document the Business Purpose Before the Technical Details
API documentation should begin by explaining what the API accomplishes.
Consider an endpoint that returns inventory information.
A technical description might say:
Returns inventory records from IBM i.
A more useful description would explain:
Retrieves current product availability for an authorized warehouse, allowing connected applications to display inventory information using approved IBM i business rules.
The second description provides business context.
It helps developers understand when the API should be used and what information they can expect.
Questions Every API Description Should Answer
- What business function does the API provide?
- Which applications should use it?
- What information does it retrieve or change?
- Which business rules apply?
- What permissions are required?
- Who owns the API?
This approach encourages organizations to document reusable business capabilities rather than individual database operations.
2. Use Consistent API Documentation Standards
As IBM i environments grow, inconsistent documentation can become a significant maintenance problem.
One team may document APIs in spreadsheets.
Another may use Word documents.
A third may maintain examples in source-code comments.
Although each approach can contain useful information, developers benefit from a consistent documentation structure.
Establish a Standard Template
Every production API should document:
- API name and description
- Endpoint URL
- HTTP method
- Authentication requirements
- Request parameters
- Request example
- Response example
- Error responses
- Business rules
- Version and ownership
A consistent format makes it easier to discover and understand APIs across the organization.
It also helps development teams identify missing information before deployment.
3. Consider OpenAPI for REST API Documentation
OpenAPI is a widely adopted specification for describing HTTP APIs in a structured, machine-readable format.
An OpenAPI description can define:
- Available endpoints
- HTTP methods
- Parameters
- Request bodies
- Response schemas
- Authentication mechanisms
- Error responses
Tools that support OpenAPI can use these descriptions to generate interactive documentation, support testing, and assist with client development.
Why OpenAPI Matters for IBM i
IBM i applications increasingly connect with development teams that use different programming languages and tools.
A standardized API description provides a common reference.
For example, a developer building a customer portal can understand the inventory API contract without needing direct knowledge of RPG programs or Db2 for i database structures.
Does OpenAPI Require Rewriting RPG?
No.
OpenAPI describes the external API interface.
It does not require organizations to replace the underlying RPG business logic.
An IBM i API can continue executing trusted RPG programs while its external interface is documented using an OpenAPI specification.
However, generating or maintaining an OpenAPI document requires appropriate documentation tooling or development processes. It should not be assumed that every RPG API toolkit automatically generates a complete OpenAPI specification.
4. Include Realistic Request and Response Examples
One of the fastest ways to help developers understand an API is to provide clear examples.
Consider an inventory lookup API.
Example Request
An application might request:
GET /api/v1/inventory/ABC123?warehouse=MAIN
Example Response
{
"productId": "ABC123",
"warehouse": "MAIN",
"availableQuantity": 125,
"availabilityStatus": "AVAILABLE"
}
Illustrative example only; not a documented Kato product endpoint.
The example demonstrates the structure of the information returned.
Documentation should explain:
- What each field represents
- Which fields are required
- What data types are used
- Whether values can be null
- Which business rules determine the result
Document More Than Successful Responses
Developers also need to understand what happens when requests fail.
For example, an invalid product identifier might produce a structured error response.
A consistent error format helps consuming applications handle failures predictably.
5. Document RPG Business Rules and Data Behavior
One of the most important differences between documenting a basic API and documenting an IBM i business API is the need to explain underlying business behavior.
An API may expose an RPG routine that performs calculations or applies rules developed over many years.
The consuming developer does not need to understand every internal implementation detail.
However, they do need to understand the behavior that affects their application.
Example: Customer Pricing API
Documentation might explain that pricing depends on:
- Customer account
- Product identifier
- Order quantity
- Contract pricing
- Effective date
- Approved discount rules
It should also describe relevant restrictions.
For example:
- What happens if the customer is inactive?
- What happens if a product is unavailable?
- Can a price be returned for an expired contract?
- Which currency is used?
- How are rounding rules applied?
Documenting these behaviors reduces the likelihood of incorrect assumptions.
Separate Business Rules from Implementation Details
Avoid exposing unnecessary internal information such as sensitive database structures, credentials, or confidential processing details.
Focus on the behavior that API consumers need to understand.
The goal is to provide a reliable contract while allowing the underlying RPG implementation to evolve.
6. Explain Authentication and Authorization Clearly
Security documentation should help developers understand how to access an API without exposing sensitive credentials.
Document:
- Supported authentication methods
- Required permissions
- Credential expiration behavior
- Appropriate request headers
- Expected authentication errors
- Access restrictions
For example, an application may be authorized to retrieve order information but not modify customer records.
Documentation should make that distinction clear.
Avoid Including Sensitive Information
Never publish:
- Production API keys
- Passwords
- Private tokens
- Internal secrets
- Sensitive customer records
Use clearly labeled sample values in documentation.
Security documentation should also explain how developers obtain approved access through the organization’s established process.
7. Keep Documentation Updated as APIs Change
API documentation can become outdated quickly when development teams change endpoints without updating their descriptions.
A new required parameter may be introduced.
An error response may change.
A field may be deprecated.
If documentation does not reflect these changes, consuming applications may fail unexpectedly.
Connect Documentation with Development Workflows
Organizations adopting modern IBM i DevOps practices can include documentation reviews as part of their development process.
For example:
- A developer modifies an RPG business function.
- The team determines whether the external API contract changes.
- The API documentation is updated.
- Automated tests verify the expected behavior.
- The change is reviewed.
- The approved version is deployed.
This helps keep documentation aligned with production behavior.
Treat Documentation as Part of the Release
A useful principle is:
An API change is not complete until its documentation is accurate.
This encourages development teams to maintain documentation continuously rather than waiting for a future cleanup project.
8. Make APIs Easy to Discover and Reuse
Even well-documented APIs provide limited value if developers cannot find them.
As organizations build more IBM i integrations, a centralized API catalog can help teams identify existing capabilities.
An API catalog might include:
- API name
- Business purpose
- Owner
- Documentation link
- Version
- Environment
- Authentication requirements
- Lifecycle status
Why API Discovery Matters
Imagine a mobile development team needs inventory availability.
Without an API catalog, the team may create a new integration because it does not know an inventory API already exists.
With a catalog, developers can discover and reuse the existing service.
This reduces duplicate development and encourages consistent integration architecture.
Reuse Creates Long-Term Value
A well-documented inventory API could support:
- eCommerce platforms
- Customer portals
- Mobile sales applications
- Warehouse systems
- Business intelligence tools
- AI assistants
The value of the API increases as more approved applications reuse the same business capability.
How RPG API Express Supports IBM i API Development
Kato Integrations’ RPG API Express helps IBM i developers build and consume web services using RPG.
The toolkit supports REST and SOAP communication along with JSON and XML composition and parsing.
For organizations modernizing existing applications, this allows developers to extend RPG business logic while continuing to work with familiar tools and programming practices.
Kato also provides product documentation, examples, and technical resources to help developers implement integrations.
These resources can support teams as they develop their own API documentation standards and reusable business interfaces.
Explore RPG API Express: https://katointegrations.com/solutions/rpg-api-express/
Explore Kato Product Documentation: https://katointegrations.com/support/documentation/
IBM i API Documentation and the Skills Gap
Documentation also plays an important role in knowledge transfer.
Many IBM i environments depend on experienced developers who understand complex applications and business rules.
When integration knowledge exists only in the original developer’s memory, organizations face additional operational risk.
Clear documentation helps:
- Reduce dependence on individual developers
- Support employee onboarding
- Simplify troubleshooting
- Improve collaboration
- Preserve business knowledge
- Accelerate future integration projects
For newer developers, documented APIs can provide a practical introduction to IBM i business capabilities without requiring immediate expertise in every underlying RPG program.
Documentation becomes part of a broader modernization strategy focused on making existing applications easier to support.
How Documentation Supports AI-Ready IBM i Integrations
As organizations evaluate AI assistants and agentic workflows, structured API documentation becomes increasingly valuable.
AI applications may need to retrieve information from IBM i through approved APIs.
For example, an AI assistant might need access to:
- Order status
- Inventory availability
- Customer information
- Product pricing
- Shipment tracking
A clear API contract helps the application or its integration layer understand which functions are available and what inputs and outputs they require.
However, documentation alone does not make an API safe for autonomous use.
Organizations must still enforce authentication, authorization, input validation, transaction limits, and appropriate human approval for consequential actions.
Well-documented APIs provide a foundation for controlled AI integration.
A Practical IBM i API Documentation Checklist
Before releasing an API, verify the following.
Business Information
- Is the API’s purpose clearly described?
- Are business rules documented?
- Is the API owner identified?
- Are expected consumers known?
Technical Information
- Is the endpoint documented?
- Are HTTP methods specified?
- Are required parameters explained?
- Are request and response examples available?
- Are data types defined?
Security
- Are authentication requirements documented?
- Are authorization restrictions clear?
- Are sensitive values excluded from examples?
- Are error responses described?
Lifecycle Management
- Is the API version identified?
- Are breaking changes documented?
- Is there a process for updating documentation?
- Can developers find the API in a central catalog?
A consistent checklist helps organizations maintain documentation quality as their integration environments grow.
A 30-Day Plan to Improve IBM i API Documentation
Organizations do not need to document every legacy integration immediately.
Start with the APIs that provide the greatest business value.
Week 1: Inventory Existing APIs
Identify production APIs and their owners.
Prioritize APIs used by customer-facing applications or critical business processes.
Week 2: Standardize Documentation
Create a documentation template covering endpoints, authentication, parameters, responses, errors, and business rules.
Week 3: Document High-Priority APIs
Add realistic examples and validate the documentation against actual API behavior.
Week 4: Establish Ongoing Maintenance
Assign ownership, introduce documentation reviews, and define how updates will be handled during future releases.
This approach creates a repeatable process without requiring a large documentation project.
Frequently Asked Questions About IBM i API Documentation
What is IBM i API documentation?
IBM i API documentation describes how applications and developers can access IBM i business functions through APIs, including endpoints, parameters, authentication, responses, errors, and business rules.
Why is API documentation important for RPG developers?
Documentation helps developers understand how APIs behave, reduces maintenance complexity, supports knowledge transfer, and makes RPG business capabilities easier for other applications to consume.
Can OpenAPI be used with IBM i REST APIs?
Yes. OpenAPI can describe REST APIs that expose IBM i business functions. The underlying application can continue using RPG while the external API interface is documented using a standardized specification.
Does OpenAPI replace RPG?
No. OpenAPI describes an API contract. RPG can continue executing the business logic behind the interface.
What should every IBM i API document?
At minimum, document the API purpose, endpoint, HTTP method, authentication, required inputs, response structure, error behavior, business rules, version, and owner.
How often should API documentation be updated?
Documentation should be reviewed whenever an API’s external behavior changes, including updates to parameters, responses, authentication, errors, or business rules.
Can documentation help reduce IBM i technical debt?
Yes. Clear documentation can reduce dependence on individual developers, improve troubleshooting, encourage reuse, and make integrations easier to maintain.
Does RPG API Express include documentation?
Kato Integrations provides product documentation, example programs, and technical resources for RPG API Express. Organizations should also document the specific business APIs they build using the toolkit.
Final Thoughts
Building an IBM i API creates a new connection between trusted business applications and modern technology.
Documenting that API makes the connection easier to understand, reuse, secure, and maintain.
As organizations expand their integration environments, IBM i API documentation becomes an important part of long-term modernization.
Clear API contracts help developers work more efficiently.
Consistent examples reduce uncertainty.
Documented business rules protect application behavior.
Versioning and ownership support ongoing maintenance.
And centralized API catalogs make reusable business capabilities easier to discover.
The goal is not simply to produce more documentation.
It’s to make every IBM i integration easier for the next developer, application, or business process to use successfully.
For organizations preparing their IBM i environments for 2027, that is a practical modernization improvement that can begin today.