From f14894054fbf5aa1ac1d1a5a141fab3d82697d01 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:54:44 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + SKILL.md | 423 +++ plugin.lock.json | 97 + references/deprecation-policy.md | 664 +++++ references/developer-guides.md | 704 +++++ references/glossary-resources.md | 472 +++ references/java-javascript-dotnet-guide.md | 1517 ++++++++++ references/manual-templates-guide.md | 2765 +++++++++++++++++ references/naming-conventions.md | 2059 +++++++++++++ references/quality-processes.md | 1774 +++++++++++ references/rest-odata-openapi-guide.md | 2800 ++++++++++++++++++ templates/odata-operation-template.md | 681 +++++ templates/odata-resource-template.md | 557 ++++ templates/odata-service-overview-template.md | 411 +++ templates/rest-api-method-template.md | 477 +++ templates/rest-api-overview-template.md | 217 ++ 17 files changed, 15633 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 plugin.lock.json create mode 100644 references/deprecation-policy.md create mode 100644 references/developer-guides.md create mode 100644 references/glossary-resources.md create mode 100644 references/java-javascript-dotnet-guide.md create mode 100644 references/manual-templates-guide.md create mode 100644 references/naming-conventions.md create mode 100644 references/quality-processes.md create mode 100644 references/rest-odata-openapi-guide.md create mode 100644 templates/odata-operation-template.md create mode 100644 templates/odata-resource-template.md create mode 100644 templates/odata-service-overview-template.md create mode 100644 templates/rest-api-method-template.md create mode 100644 templates/rest-api-overview-template.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..a274bda --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "sap-api-style", + "description": "Comprehensive guidance for documenting SAP APIs following official SAP API Style Guide standards. Covers REST, OData, OpenAPI, Javadoc, JSDoc, and API Business Hub compliance.", + "version": "1.0.0", + "author": { + "name": "Zhongwei Li", + "email": "zhongweili@tubi.tv" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..39a15b2 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# sap-api-style + +Comprehensive guidance for documenting SAP APIs following official SAP API Style Guide standards. Covers REST, OData, OpenAPI, Javadoc, JSDoc, and API Business Hub compliance. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..bdf5b1f --- /dev/null +++ b/SKILL.md @@ -0,0 +1,423 @@ +--- +name: sap-api-style +description: | + This skill provides comprehensive guidance for documenting SAP APIs following official SAP API Style Guide standards. + It should be used when creating or reviewing API documentation for REST, OData, Java, JavaScript, .NET, or C/C++ APIs. + + The skill covers naming conventions, documentation comments, OpenAPI specifications, quality checklists, deprecation policies, + and manual documentation templates. It ensures consistency with SAP API Business Hub standards and industry best practices. + + Keywords: SAP API, REST, OData, OpenAPI, Swagger, Javadoc, JSDoc, XML documentation, API Business Hub, API naming, + API deprecation, x-sap-stateInfo, Entity Data Model, EDM, documentation tags, API quality, API templates +license: GPL-3.0 +metadata: + version: "1.1.0" + last_verified: "2025-11-27" + source_version: "2025.01" + source_commit: "902247f3afb6a0cb3fa110b284bb5d93a65c1268" + source_license: "CC-BY-4.0" +--- + +# SAP API Style Guide + +## Related Skills + +- **sap-cap-capire**: Use for OData service documentation, CAP API patterns, and service definition standards +- **sap-fiori-tools**: Use for API consumption patterns, Fiori app integration, and OData best practices +- **sap-abap**: Use when documenting ABAP APIs, implementing REST services, or following API design patterns +- **sapui5**: Use for frontend API integration, OData consumption, and UI service patterns +- **sap-btp-cloud-platform**: Use for BTP service API documentation and integration patterns + +## Table of Contents + +1. [Overview](#overview) +2. [When to Use This Skill](#when-to-use-this-skill) +3. [Quick Decision Tree](#quick-decision-tree) +4. [Core Principles](#core-principles) +5. [Quick Reference Tables](#quick-reference-tables) +6. [Templates Available](#templates-available) +7. [Reference Files](#reference-files) +8. [Instructions for Use](#instructions-for-use) +9. [Common Pitfalls to Avoid](#common-pitfalls-to-avoid) +10. [External Resources](#external-resources) +11. [Updates and Maintenance](#updates-and-maintenance) + +## Overview + +This skill provides comprehensive guidance for documenting SAP APIs according to official SAP API Style Guide standards. It covers all major API types and documentation approaches used across the SAP ecosystem. + +**Documentation Source**: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide) (76 files extracted) + +**Last Verified**: 2025-11-21 + +## When to Use This Skill + +Use this skill when: + +- **Creating API documentation** for REST, OData, Java, JavaScript, .NET, or C/C++ APIs +- **Writing OpenAPI specifications** for SAP API Business Hub +- **Reviewing API names** for SAP naming convention compliance +- **Documenting API parameters, responses, operations** with proper formatting +- **Creating manual API documentation** using SAP templates +- **Writing documentation comments** in source code (Javadoc, JSDoc, XML comments) +- **Implementing API deprecation** following SAP lifecycle policies +- **Developing developer guides** or service documentation +- **Performing quality checks** on API documentation +- **Publishing APIs** to SAP API Business Hub + +## Quick Decision Tree + +### What Type of API? + +``` +REST/OData API +├─ Auto-generated (OpenAPI/Swagger)? +│ └─ references/rest-odata-openapi-guide.md +│ • OpenAPI specification standards +│ • Package, API, operation descriptions +│ • Parameters, responses, components +│ • SAP API Business Hub requirements +│ +└─ Manually written? + └─ references/manual-templates-guide.md + • REST templates (2-level: overview → method) + • OData templates (3-level: service → resource → operation) + • Complete field requirements + • templates/ directory for ready-to-use files + +Native Library API +├─ Java → references/java-javascript-dotnet-guide.md +├─ JavaScript → references/java-javascript-dotnet-guide.md +├─ .NET (C#) → references/java-javascript-dotnet-guide.md +└─ C/C++ → references/java-javascript-dotnet-guide.md + • Documentation comments structure + • Language-specific tags + • Templates for classes, methods, enums + • Complete code examples +``` + +### What Task? + +``` +Naming +└─ references/naming-conventions.md + • REST/OData naming (resources, parameters, URIs) + • Native library naming (classes, methods, constants) + • Common mistakes to avoid + +Writing Descriptions +└─ references/rest-odata-openapi-guide.md + • Package descriptions + • API details (info object) + • Operations, parameters, responses + +Quality Assurance +└─ references/quality-processes.md + • Complete API Quality Checklist + • Review workflows + • Development team guidelines + +Deprecating APIs +└─ references/deprecation-policy.md + • Lifecycle states (beta, active, deprecated, decommissioned) + • Timeline requirements (12+ months support) + • Required metadata (x-sap-stateInfo) + +Developer Guides +└─ references/developer-guides.md + • Structure guidelines + • Content selection + • Code sample standards +``` + +## Core Principles + +### 1. Consistency Across SAP APIs + +All SAP API documentation follows consistent conventions: +- **Naming**: Language-specific (camelCase, PascalCase, kebab-case) +- **Structure**: Hierarchical with clear navigation +- **Formatting**: Sentences start with capitals, end with periods +- **Language**: American English + +### 2. API-Type-Specific Standards + +| API Type | Standard | Tool | Documentation | +|----------|----------|------|---------------| +| REST | OpenAPI 3.0.3 | Swagger | [Spec](https://spec.openapis.org/) | +| OData | v4.01, v3.0, v2.0 | Various | [OData.org](https://www.odata.org/) | +| Java | Javadoc | javadoc | [Oracle](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) | +| JavaScript | JSDoc 3 | jsdoc | [JSDoc.app](https://jsdoc.app/) | +| .NET | XML Comments | DocFX | [Microsoft](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) | +| C/C++ | Doxygen | doxygen | [Doxygen.nl](https://www.doxygen.nl/) | + +### 3. Progressive Disclosure + +Documentation organized hierarchically: +- **High-level overviews** provide context and navigation +- **Detailed references** cover specific APIs, methods, operations +- **Examples and templates** demonstrate practical usage + +### 4. Quality Standards + +All documentation must: +- ✅ Be reviewed by User Assistance (UA) developers +- ✅ Use consistent naming and terminology +- ✅ Include complete parameter and response descriptions +- ✅ Avoid sensitive data in examples +- ✅ Provide working code examples +- ✅ Maintain accurate links and cross-references + +## Quick Reference Tables + +### Character Limits + +| Element | Limit | Use Case | +|---------|-------|----------| +| API Title | 80 | `info.title` in OpenAPI | +| API Short Text | 180 | `x-sap-shortText` | +| Package Short Desc | 250 | Package tile description | +| Operation Summary | 255 | Operation summary line | +| Description | 1024 | General descriptions | + +### API Naming Rules + +**General Rules** (all API types): +- ❌ Don't include "API" in name: ~~"Custom Forms API"~~ → ✅ "Custom Forms" +- ❌ Don't include "SAP" prefix: ~~"SAP Document Approval"~~ → ✅ "Document Approval" +- ❌ Don't use verbs: ~~"Configuring Portal"~~ → ✅ "Portal Configuration" +- ✅ Capitalize words properly +- ✅ Avoid technical specifics (REST, OData, etc.) + +See `references/naming-conventions.md` for complete language-specific rules. + +### Common Documentation Tags + +**Java/JavaScript**: +- `@param ` - Parameter documentation +- `@return ` - Return value +- `@throws ` - Exception +- `@deprecated ` - Deprecation notice + +**.NET**: +- `` - Brief description +- `` - Parameter +- `` - Return value +- `` - Exception + +See `references/java-javascript-dotnet-guide.md` for complete tag reference. + +### API Lifecycle States + +| State | Definition | Support | Metadata Required | +|-------|-----------|---------|-------------------| +| **Beta** | Pre-production testing | No guarantees | `state: beta` | +| **Active** | Production-ready (default) | Full support | Optional | +| **Deprecated** | Replaced by successor | 12+ months | `state`, `deprecationDate`, `successorApi` | +| **Decommissioned** | Fully retired | None | Document removal | + +See `references/deprecation-policy.md` for complete timeline and process requirements. + +## Templates Available + +Ready-to-use templates in `templates/` directory: + +### REST API Templates (2-Level) +1. **rest-api-overview-template.md** - Resource-level overview +2. **rest-api-method-template.md** - Individual endpoint details + +### OData API Templates (3-Level) +1. **odata-service-overview-template.md** - Complete service overview +2. **odata-resource-template.md** - Individual resource/entity set +3. **odata-operation-template.md** - Specific operation details + +All templates include: +- Clear "How to Use" instructions +- [Placeholder text] for customization +- Complete section structure +- Working examples +- Inline guidance + +## Reference Files + +### Complete Guides Available + +1. **rest-odata-openapi-guide.md** (2,800 lines) + - Complete OpenAPI specification guidelines + - Package, API, operation descriptions + - Parameters, responses, components + - Security schemes, tags, external docs + - Character limits and anti-patterns + +2. **manual-templates-guide.md** (2,765 lines) + - REST API templates (2-level hierarchy) + - OData API templates (3-level hierarchy) + - Complete template structures + - Field-by-field requirements + - Best practices and examples + +3. **naming-conventions.md** (2,059 lines) + - REST/OData naming rules (resources, parameters, URIs) + - Native library naming (classes, methods, constants, packages) + - Language-specific conventions + - Common mistakes with fixes + - Decision trees and reference tables + +4. **quality-processes.md** (1,774 lines) + - Complete API Quality Checklist + - Review workflows (developer + UA collaboration) + - Development team guidelines + - Common review findings and solutions + - Process flowcharts + +5. **java-javascript-dotnet-guide.md** (1,517 lines) + - Documentation comments structure + - Language-specific tags (Java, JavaScript, .NET, C/C++) + - Templates for classes, methods, enums + - Complete code examples + - Best practices by language + +6. **developer-guides.md** (704 lines) + - Guide structure standards + - Topic types (concept, reference, task) + - Content selection criteria + - Code sample standards (compilable, concise, commented) + - Best practices + +7. **deprecation-policy.md** (664 lines) + - API lifecycle states (beta, active, deprecated, decommissioned) + - Timeline requirements (12+ months support, 24+ months lifespan) + - Required metadata (x-sap-stateInfo, artifact.json) + - Decommission process + - Complete examples + +8. **glossary-resources.md** (472 lines) + - Complete terminology definitions (API, OData, OpenAPI, etc.) + - External resource links (standards, tools, SAP resources) + - Quick reference tables + - Tool documentation links + + - Content extraction and organization tracking + - Source file mapping from SAP documentation + - Consolidation and adaptation notes + +## Bundled Resources + +This skill includes comprehensive documentation and templates organized for optimal use: + +### Reference Guides (`references/`) +- 9 detailed reference files (10,861 total lines) +- Complete coverage of SAP API Style Guide standards +- Progressive disclosure architecture for efficient loading + +### Template Files (`templates/`) +1. **rest-api-overview-template.md** (217 lines) - Level 1 REST overview +2. **rest-api-method-template.md** (477 lines) - Level 2 REST method details +3. **odata-service-overview-template.md** (411 lines) - Level 1 OData service +4. **odata-resource-template.md** (557 lines) - Level 2 OData resource +5. **odata-operation-template.md** (681 lines) - Level 3 OData operation + +Total: 2,343 lines of ready-to-use templates + +## Instructions for Use + +### Step 1: Identify API Type + +Determine if you're documenting REST, OData, Java, JavaScript, .NET, or C/C++ API. + +### Step 2: Choose Approach + +**Auto-Generated**: Write documentation comments in source code → Use appropriate tags → Submit for review + +**Manual**: Select template from `templates/` → Customize [placeholders] → Follow hierarchy → Validate with checklist + +### Step 3: Apply Standards + +Consult appropriate reference file: +- **Naming**: `naming-conventions.md` +- **Descriptions**: `rest-odata-openapi-guide.md` or `java-javascript-dotnet-guide.md` +- **Quality**: `quality-processes.md` +- **Deprecation**: `deprecation-policy.md` + +### Step 4: Quality Check + +Before publishing: +1. Review against API Quality Checklist (`quality-processes.md`) +2. Verify naming conventions (`naming-conventions.md`) +3. Check character limits (see Quick Reference Tables above) +4. Validate no sensitive data in examples +5. Test all code examples +6. Verify links work +7. Obtain UA developer review + +### Step 5: Publish + +- **REST/OData**: Submit to SAP API Business Hub +- **Java/JavaScript/.NET**: Generate with appropriate tool (Javadoc, JSDoc, DocFX) +- **Developer Guides**: Publish to SAP Help Portal or product documentation + +## Common Pitfalls to Avoid + +**Naming**: +- ❌ Including "API": ~~"Custom Forms APIs"~~ → ✅ "Custom Forms" +- ❌ Using "SAP" prefix: ~~"SAP Document Approval"~~ → ✅ "Document Approval" +- ❌ Using verbs: ~~"Configuring Portal"~~ → ✅ "Portal Configuration" + +**Descriptions**: +- ❌ Second person: ~~"This operation creates..."~~ → ✅ "Creates a new user" +- ❌ Generic responses: ~~"No content"~~ → ✅ "Product is out of stock" +- ❌ Repeating summary in description + +**Documentation**: +- ❌ Skipping UA review +- ❌ Including sensitive data in examples +- ❌ Missing required tags +- ❌ Inconsistent terminology + +See individual reference files for complete anti-patterns and fixes. + +## External Resources + +### Standards +- **OpenAPI Specification**: [https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html) +- **OData v4.01**: [https://www.odata.org/documentation/](https://www.odata.org/documentation/) +- **Javadoc**: [https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) +- **JSDoc 3**: [https://jsdoc.app/](https://jsdoc.app/) +- **Doxygen**: [https://www.doxygen.nl/](https://www.doxygen.nl/) + +### SAP Resources +- **SAP API Business Hub**: [https://api.sap.com/](https://api.sap.com/) +- **SAP Developer Center**: [https://developers.sap.com/](https://developers.sap.com/) +- **SAP Help Portal**: [https://help.sap.com/](https://help.sap.com/) +- **SAP Community**: [https://community.sap.com/](https://community.sap.com/) + +### Source +- **SAP API Style Guide**: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide) + +## Updates and Maintenance + +**Source Version**: SAP API Style Guide 2025.01 (verified against commit 902247f) + +**Recent Changes**: +- Source repository updated 2025-10-28 +- Reference file line counts verified and updated +- Added comprehensive Table of Contents for navigation +- Added Bundled Resources section for content discovery + +**To Update This Skill**: +1. Check source repository for changes: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide) +2. Review "What's New in the Style Guide" +3. Update affected reference files +4. Update templates if standards changed +5. Update "Last Verified" date + +**Quarterly Review Recommended**: Check for updates every 3 months + +**Next Review**: 2026-02-27 + +--- + +**Skill Version**: 1.1.0 +**Last Updated**: 2025-11-27 +**License**: GPL-3.0 +**Maintainer**: SAP Skills Team | [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills) diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7e2893f --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,97 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:secondsky/sap-skills:skills/sap-api-style", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "09539a98b0dc5ce0f7a028ed8e8cab96d1c3fe1c", + "treeHash": "6f7f6999b5610c56069d2170c4f46ed9e4ebc4ebdd807e487b188f7de24a5b7c", + "generatedAt": "2025-11-28T10:28:10.900382Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "sap-api-style", + "description": "Comprehensive guidance for documenting SAP APIs following official SAP API Style Guide standards. Covers REST, OData, OpenAPI, Javadoc, JSDoc, and API Business Hub compliance.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "bd8bef477b2a94275b53eec22d0933e1d58ca04047f0efebca7cc46d7d8d0130" + }, + { + "path": "SKILL.md", + "sha256": "af2099a2f3dfcc3d089d0faae30f6d45e65c5432267a13c1dffb09bfccc4a5f6" + }, + { + "path": "references/developer-guides.md", + "sha256": "b340234e627f4592b5f3d43c27b81ed853b222b8efd84ba927dedb0e6e95d12d" + }, + { + "path": "references/deprecation-policy.md", + "sha256": "afb9ae0ddd799899e2fa020c43de3d249abf70d7dbb9dd7af4ce2eea31b9e0a4" + }, + { + "path": "references/naming-conventions.md", + "sha256": "10e0719a15752ba251eeafc999a4061b767b30d106f76fad61314830be446c79" + }, + { + "path": "references/glossary-resources.md", + "sha256": "a28da9075d577298cb2f6e1b7aba4537eb2d8684c6a344eb087156b38922a7ce" + }, + { + "path": "references/java-javascript-dotnet-guide.md", + "sha256": "b542327631952576a17618975de1cb99b75b037422d674e7bb8dbd575e99a9cb" + }, + { + "path": "references/rest-odata-openapi-guide.md", + "sha256": "8afd1e9a7578cc1a59ccdb4cebf18cd44c0f7f479afe86d559d7cc06a719d209" + }, + { + "path": "references/manual-templates-guide.md", + "sha256": "8b9d56b99c47ae1fc723a64c46b0961041f4319a58f66c0668066e45b31be9b1" + }, + { + "path": "references/quality-processes.md", + "sha256": "c7529c41d605ae9b9bb3ea361dc511860e452d08397af6d5f81ceaefb982839b" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "b0b221e769fd1b7d918fe89a7d690aca233ec782ac72becc6c6f47ee3a319655" + }, + { + "path": "templates/rest-api-method-template.md", + "sha256": "10883dffee3ff7ebc73729d71468b3b4c5f67afaa03fd7c85b4bb84b5f8c6c48" + }, + { + "path": "templates/odata-service-overview-template.md", + "sha256": "3da25ef899201d5db2bab983515a7ffffa939986da99dae1365316b090baa73d" + }, + { + "path": "templates/rest-api-overview-template.md", + "sha256": "fd3f197ac57124105613351105978a41935d5f0746a410e287c035686cfa6f45" + }, + { + "path": "templates/odata-operation-template.md", + "sha256": "8156816cebacdd820aedc8ac0f42b90ff87705e944064cffc8f1371b2a649a48" + }, + { + "path": "templates/odata-resource-template.md", + "sha256": "c8f0b49a39e53847a20b53874a347b88dc172be3cfa440a4c3fb8b9d2f3d2ec4" + } + ], + "dirSha256": "6f7f6999b5610c56069d2170c4f46ed9e4ebc4ebdd807e487b188f7de24a5b7c" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/references/deprecation-policy.md b/references/deprecation-policy.md new file mode 100644 index 0000000..3cd1122 --- /dev/null +++ b/references/deprecation-policy.md @@ -0,0 +1,664 @@ +# SAP API Deprecation Policy + +**Source**: [https://github.com/SAP-docs/api-style-guide/blob/main/docs/api-deprecation-policy-65a10e3.md](https://github.com/SAP-docs/api-style-guide/blob/main/docs/api-deprecation-policy-65a10e3.md) +**Last Verified**: 2025-11-21 + +**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)) + +**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates. + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [API Lifecycle States](#api-lifecycle-states) +3. [Timeline Requirements](#timeline-requirements) +4. [Required Metadata](#required-metadata) +5. [Stakeholder Responsibilities](#stakeholder-responsibilities) +6. [Deprecation Process](#deprecation-process) +7. [Decommission Process](#decommission-process) +8. [Best Practices](#best-practices) +9. [Examples](#examples) + +--- + +## Overview + +### Core Definition + +A **deprecated API** "is no longer supported in future releases, and therefore not encouraged for use." + +A **decommissioned API** has been fully retired and cannot be used in production. + +### Key Principles + +1. **Transparency**: Clearly communicate API lifecycle state to consumers +2. **Predictability**: Provide adequate notice before decommissioning +3. **Support**: Maintain deprecated APIs for minimum periods +4. **Documentation**: Update all documentation to reflect current state +5. **Migration Guidance**: Provide clear paths to successor APIs + +--- + +## API Lifecycle States + +SAP APIs use the `x-sap-stateInfo` attribute to define four lifecycle states: + +### 1. Beta + +**Definition**: Pre-production testing phase + +**Characteristics**: +- Available for testing and evaluation +- May have incompatible changes without notice +- Not recommended for production use +- No support guarantees + +**Use Case**: Early adopters testing new functionality + +**Metadata**: +```yaml +x-sap-stateInfo: + state: beta +``` + +### 2. Active + +**Definition**: Live production-ready APIs + +**Characteristics**: +- Fully supported for production use +- Backward compatibility maintained +- Default status (can be omitted from metadata) +- Full support and SLAs apply + +**Use Case**: Standard production API usage + +**Metadata**: +```yaml +x-sap-stateInfo: + state: active +``` + +Or simply omit the attribute (active is default). + +### 3. Deprecated + +**Definition**: Live but replaced by an active successor + +**Characteristics**: +- Still functional and supported (temporarily) +- Not recommended for new implementations +- Requires migration to successor API +- Support period defined (minimum 12 months) +- Must include deprecation date and successor information + +**Use Case**: Legacy APIs being phased out + +**Metadata**: +```yaml +x-sap-stateInfo: + state: deprecated + deprecationDate: "2024-01-15" + successorApi: "NewAPIName v2.0" +``` + +### 4. Decommissioned + +**Definition**: Retired from production + +**Characteristics**: +- No longer functional +- Cannot be used in any environment +- Removed from documentation +- No support available + +**Use Case**: Fully retired APIs + +**Implementation**: Remove from artifact or mark in changelog + +--- + +## Timeline Requirements + +### Minimum Support Period After Deprecation + +**12 months minimum** support period after deprecation announcement + +**Calculation**: +- Starts from deprecation announcement date +- Continues until decommission date +- Allows customers adequate migration time + +**Example Timeline**: +``` +Jan 15, 2024: API deprecated (announcement) +Jan 15, 2025: Earliest decommission date (12 months later) +``` + +### Minimum Total Lifespan + +**24 months minimum** total lifespan in active or deprecated status before decommissioning + +**Calculation**: +- Starts from initial active release +- Includes time in active state + time in deprecated state +- Ensures reasonable API stability + +**Example Timeline**: +``` +Jan 1, 2022: API released (active) +Jan 1, 2024: API deprecated (24 months active) +Jan 1, 2025: Earliest decommission (12 months deprecated) + +Alternative: +Jan 1, 2022: API released (active) +Jun 1, 2022: API deprecated (6 months active) +Jun 1, 2024: Earliest decommission (18 months deprecated, 24 total) +``` + +### Best Practice Timeline + +SAP recommends: +- **Active period**: 18-36 months before deprecation +- **Deprecation period**: 12-24 months before decommission +- **Total lifespan**: 30+ months for production APIs + +--- + +## Required Metadata + +### OpenAPI Specification + +APIs must include `x-sap-stateInfo` object in the OpenAPI specification file: + +```yaml +openapi: 3.0.0 +info: + title: Employee Management API + version: 1.5.0 + x-sap-stateInfo: + state: deprecated + deprecationDate: "2024-01-15" + successorApi: "Employee Management API v2.0" +``` + +**Required Fields for Deprecated APIs**: +- `state`: Must be "deprecated" +- `deprecationDate`: ISO 8601 date format (YYYY-MM-DD) +- `successorApi`: Name and version of replacement API + +### Artifact.json + +APIs must include changelog entries in `artifact.json`: + +```json +{ + "changelog": [ + { + "state": "deprecated", + "date": "2024-01-15", + "version": "1.5.0", + "notes": "Deprecated in favor of Employee Management API v2.0. Migration guide available at [https://help.sap.com/migration-guide"](https://help.sap.com/migration-guide") + }, + { + "state": "active", + "date": "2022-01-01", + "version": "1.0.0", + "notes": "Initial release" + } + ] +} +``` + +**Required Fields**: +- `state`: Current API state +- `date`: State change date (ISO 8601 format) +- `version`: API version at state change +- `notes`: Descriptive information about the change + +--- + +## Stakeholder Responsibilities + +### Product Owners + +**Lifecycle Decisions**: +- Determine when to deprecate APIs +- Decide deprecation timelines +- Identify successor APIs +- Approve decommission schedules + +**Metadata Configuration**: +- Ensure `x-sap-stateInfo` properly configured +- Maintain accurate `artifact.json` changelog +- Verify metadata consistency across systems + +**Communication**: +- Announce deprecation through release notes +- Publish blog posts about major deprecations +- Notify affected customers directly +- Provide migration timelines + +**Support Management**: +- Maintain support during deprecation period +- Allocate resources for customer migration assistance +- Track migration progress +- Coordinate decommission activities + +### UA (User Assistance) Developers + +**Documentation Updates**: +- Add deprecation notices to API documentation +- Update API reference pages with warnings +- Create prominent deprecation banners +- Link to successor API documentation + +**Decommission Documentation**: +- Remove links to decommissioned APIs +- Archive old documentation appropriately +- Redirect old URLs to successor documentation +- Update navigation and search indices + +**Source Code Tags**: +- Apply `@deprecated` tag in Javadoc/JSDoc comments +- Include deprecation reason and alternative +- Update inline documentation +- Add migration code examples + +**Migration Guidance**: +- Create migration guides in release notes +- Document API differences +- Provide code migration examples +- Publish before-and-after comparisons + +### Development Teams + +**Code Maintenance**: +- Continue bug fixes during deprecation period +- Maintain security patches +- No new feature development +- Plan removal timeline + +**Testing**: +- Maintain test coverage during deprecation +- Test successor API thoroughly +- Validate migration paths +- Monitor customer usage patterns + +--- + +## Deprecation Process + +### Step 1: Decision and Planning + +1. **Assess API Usage**: + - Review usage metrics and analytics + - Identify affected customers + - Estimate migration effort + +2. **Define Successor**: + - Identify replacement API + - Document migration path + - Create migration guide + +3. **Set Timeline**: + - Calculate minimum support period (12 months) + - Verify total lifespan requirement (24 months) + - Set deprecation and decommission dates + +### Step 2: Update Metadata + +1. **OpenAPI Specification**: +```yaml +x-sap-stateInfo: + state: deprecated + deprecationDate: "2024-01-15" + successorApi: "NewAPI v2.0" +``` + +2. **Artifact.json**: +```json +{ + "changelog": [{ + "state": "deprecated", + "date": "2024-01-15", + "version": "1.5.0", + "notes": "Deprecated. Use NewAPI v2.0. Migration guide: [https://..."](https://...") + }] +} +``` + +3. **Source Code** (Java example): +```java +/** + * Gets customer address. + * + * @deprecated As of version 1.5.0, replaced by + * {@link com.sap.newapi.Customer#getAddress()} + * Use the new API which provides enhanced address validation. + */ +@Deprecated +public Address getCustomerAddress() { + // implementation +} +``` + +### Step 3: Documentation Updates + +1. **API Reference**: + - Add deprecation banner at top of page + - Include deprecation date and successor + - Link to migration guide + +2. **Release Notes**: + - Announce deprecation + - Explain reason for deprecation + - Provide migration timeline + - Link to migration guide + +3. **Migration Guide**: + - Document API differences + - Provide code examples + - Explain migration steps + - List breaking changes + +### Step 4: Communication + +1. **Announcement Channels**: + - Release notes + - Blog posts + - Email to affected customers + - In-app notifications (if applicable) + +2. **Announcement Content**: + - What is being deprecated + - Why it's being deprecated + - When it will be decommissioned + - What to use instead + - Where to find migration guidance + +### Step 5: Support Period + +1. **Maintain Support**: + - Continue bug fixes + - Provide security patches + - Answer customer questions + - Monitor migration progress + +2. **Track Migration**: + - Monitor API usage metrics + - Identify customers still using deprecated API + - Proactively contact stragglers + - Offer migration assistance + +--- + +## Decommission Process + +### Prerequisites + +Before decommissioning, verify: +- [ ] Minimum 12 months since deprecation announcement +- [ ] Minimum 24 months total lifespan +- [ ] All customers notified +- [ ] Migration guidance published +- [ ] Successor API available and stable +- [ ] Remaining usage is minimal + +### Decommission Methods + +#### Method 1: Remove Entire API Package + +**For complete API removal**: + +1. Delete artifact folder from repository +2. Commit and push changes +3. Republish to SAP API Business Hub (API will be removed) + +**Example**: +```bash +# Remove the API directory +rm -rf apis/EmployeeManagement/1.0 + +# Commit removal +git add -A +git commit -m "Decommission EmployeeManagement API v1.0" +git push +``` + +#### Method 2: Remove Specific Endpoints + +**For partial API removal**: + +1. Edit `artifact.json` +2. Remove specific endpoint definitions +3. Update changelog with decommission notice +4. Commit and push changes + +**Example** (`artifact.json`): +```json +{ + "changelog": [ + { + "state": "decommissioned", + "date": "2025-01-15", + "version": "1.5.0", + "notes": "Endpoint /legacy/customers decommissioned. Use /v2/customers instead." + } + ], + "paths": { + "/v2/customers": { ... } + // Removed: "/legacy/customers" + } +} +``` + +### Post-Decommission Actions + +1. **Documentation Cleanup**: + - Remove API from documentation site + - Archive old documentation + - Set up redirects to successor API + - Update navigation menus + +2. **URL Management**: + - Configure HTTP 410 (Gone) responses for old endpoints + - Include message pointing to successor API + - Maintain redirects for reasonable period + +3. **Communication**: + - Publish decommission announcement + - Send final notification to any remaining users + - Update status pages + +--- + +## Best Practices + +### Planning + +1. **Early Assessment**: Evaluate deprecation candidates during product planning +2. **Customer Impact**: Always consider customer migration effort +3. **Batch Deprecations**: Group related API deprecations together +4. **Version Strategy**: Use semantic versioning to signal breaking changes + +### Communication + +1. **Multiple Channels**: Announce through all available channels +2. **Advance Notice**: Provide notice well before minimum period +3. **Clear Messaging**: Explain what, why, when, and how +4. **Regular Reminders**: Send periodic reminders during deprecation period + +### Documentation + +1. **Prominent Warnings**: Make deprecation notices highly visible +2. **Complete Migration Guides**: Don't just say "use X instead" - explain how +3. **Code Examples**: Provide before/after code comparisons +4. **FAQs**: Answer common migration questions + +### Technical + +1. **Graceful Degradation**: Consider warning headers before hard removal +2. **Usage Tracking**: Monitor deprecated API usage +3. **Migration Tools**: Provide automated migration tools when feasible +4. **Backward Compatibility**: Maintain during deprecation period + +--- + +## Examples + +### Example 1: REST API Endpoint Deprecation + +**OpenAPI Specification**: +```yaml +openapi: 3.0.0 +info: + title: Order Management API + version: 2.1.0 + +paths: + /orders/{orderId}: + get: + summary: Get order details + deprecated: true + description: | + **DEPRECATED**: This endpoint is deprecated as of January 15, 2024. + Use /v2/orders/{orderId} instead. + + This endpoint will be decommissioned on January 15, 2025. + + Migration guide: [https://help.sap.com/order-api-migration](https://help.sap.com/order-api-migration) + x-sap-stateInfo: + state: deprecated + deprecationDate: "2024-01-15" + successorApi: "/v2/orders/{orderId}" + responses: + '200': + description: Order details (deprecated) + headers: + Warning: + schema: + type: string + description: '299 - "Deprecated API. Use /v2/orders/{orderId}"' +``` + +### Example 2: Java Method Deprecation + +```java +/** + * Service for managing customer data. + */ +public class CustomerService { + + /** + * Retrieves customer by ID. + * + * @param customerId the customer identifier + * @return customer object + * @throws NotFoundException if customer not found + * @deprecated As of version 2.0.0 (deprecated January 15, 2024), + * replaced by {@link #getCustomerById(String)} + * The new method provides enhanced validation and + * supports additional customer types. + * This method will be removed in version 3.0.0 + * (scheduled for January 15, 2025). + * Migration guide: [https://help.sap.com/customer-api-migration](https://help.sap.com/customer-api-migration) + */ + @Deprecated(since = "2.0.0", forRemoval = true) + public Customer getCustomer(int customerId) throws NotFoundException { + // Legacy implementation + return legacyCustomerRetrieval(customerId); + } + + /** + * Retrieves customer by ID with enhanced validation. + * + * @param customerId the customer identifier (supports all formats) + * @return customer object + * @throws NotFoundException if customer not found + * @throws ValidationException if customerId format invalid + * @since 2.0.0 + */ + public Customer getCustomerById(String customerId) + throws NotFoundException, ValidationException { + // New implementation + return enhancedCustomerRetrieval(customerId); + } +} +``` + +### Example 3: Complete API Deprecation Timeline + +**Timeline**: Document Management API + +``` +2022-01-01: API v1.0.0 released (active) +├─ State: active +├─ Full support and SLAs +└─ Production-ready + +2023-06-15: API v2.0.0 released +├─ Enhanced features +├─ Better performance +└─ v1.0.0 remains active + +2024-01-15: API v1.0.0 deprecated +├─ State: deprecated +├─ Deprecation announcement published +├─ Migration guide released +├─ Support continues +└─ x-sap-stateInfo updated + +2024-07-15: 6-month reminder +├─ Email to remaining v1.0.0 users +├─ 6 months until decommission +└─ Migration assistance offered + +2024-10-15: 3-month reminder +├─ Final migration push +├─ Direct contact to high-usage customers +└─ Migration tools provided + +2025-01-15: API v1.0.0 decommissioned +├─ State: decommissioned +├─ Endpoints return HTTP 410 Gone +├─ Documentation removed +├─ Redirects to v2.0.0 documentation +└─ Final announcement published + +Total Timeline: +- Active period: 24 months (Jan 2022 - Jan 2024) +- Deprecated period: 12 months (Jan 2024 - Jan 2025) +- Total lifespan: 36 months ✓ (exceeds 24-month minimum) +- Support after deprecation: 12 months ✓ (meets minimum) +``` + +--- + +## Reference + +### External Standards + +- **OpenAPI Specification**: [https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html) +- **Semantic Versioning**: [https://semver.org/](https://semver.org/) +- **HTTP Status Codes**: [https://httpstatuses.com/](https://httpstatuses.com/) + +### SAP Resources + +- **SAP API Business Hub**: [https://api.sap.com/](https://api.sap.com/) +- **SAP Help Portal**: [https://help.sap.com/](https://help.sap.com/) + +### Related Documentation + +- API Naming Guidelines +- API Quality Checklist +- API Review Process +- Developer Guide Standards + +--- + +**Document Version**: 1.0.0 +**Last Updated**: 2025-11-21 +**Maintainer**: SAP Skills Team | [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills) diff --git a/references/developer-guides.md b/references/developer-guides.md new file mode 100644 index 0000000..244a45c --- /dev/null +++ b/references/developer-guides.md @@ -0,0 +1,704 @@ +# Developer and Service Guides + +**Source**: [https://github.com/SAP-docs/api-style-guide/tree/main/docs/60-developer-or-service-guide](https://github.com/SAP-docs/api-style-guide/tree/main/docs/60-developer-or-service-guide) +**Last Verified**: 2025-11-21 + +**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)) + +**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates. + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Purpose and Scope](#purpose-and-scope) +3. [Content Structure Guidelines](#content-structure-guidelines) +4. [Topic Types and Conventions](#topic-types-and-conventions) +5. [Content Selection Guidelines](#content-selection-guidelines) +6. [Code Sample Standards](#code-sample-standards) +7. [Best Practices](#best-practices) +8. [Examples](#examples) + +--- + +## Overview + +Developer and service guides are supplementary resources that explain how to use APIs, SDKs, and development platforms alongside API references. + +### Relationship to API Reference Documentation + +| Documentation Type | Purpose | Content | +|-------------------|---------|---------| +| **API Reference** | Technical specification | Auto-generated docs, parameters, responses, methods | +| **Developer Guide** | Practical usage | Concepts, tutorials, scenarios, best practices | + +**Key Principle**: Developer guides complement API references by providing context, examples, and practical guidance that cannot be auto-generated. + +--- + +## Purpose and Scope + +### What Developer Guides Include + +1. **Conceptual Information** + - Goal, scope, and capabilities of an API + - Architectural diagrams explaining API structure + - System context and integration points + - Business scenarios and use cases + +2. **Code Quality Practices** + - Secure programming guidelines + - Resilience patterns and error handling + - Performance optimization techniques + - Best practices for API consumption + +3. **Access & Setup** + - Security requirements and authentication + - Initial setup and configuration + - Environment preparation + - Prerequisites and dependencies + +4. **Practical Usage** + - Typical tasks and scenarios + - Workflows combining multiple API calls + - Sample code and tutorials + - Common integration patterns + +### Variability Across Products + +Developer guides vary significantly in: +- **Scope**: From single API to entire platform +- **Complexity**: From simple tutorials to comprehensive system documentation +- **Depth**: From quick-start guides to architectural deep-dives +- **Audience**: From beginners to advanced developers + +**Important Note**: Due to this variability, a one-size-fits-all standard is impractical. These guidelines provide flexible frameworks that technical writers adapt based on product needs and target audience. + +--- + +## Content Structure Guidelines + +### Fundamental Information Design + +Developer guides should follow these structural principles: + +1. **Separation by Type** + - Separate chapters for **concepts**, **tasks**, and **reference** material + - Clear boundaries between information types + - Logical progression from concepts → tasks → reference + +2. **Task-Oriented Approach** + - Enable rapid developer task completion + - Focus on practical outcomes + - "How do I...?" questions should be easily answerable + +3. **Consistent Title Conventions** + - Use standardized titling patterns (see Topic Types below) + - Maintain consistency throughout documentation + - Make topics easily scannable + +--- + +## Topic Types and Conventions + +### Topic Type Matrix + +| Type | Purpose | Title Format | Example | Content | +|------|---------|--------------|---------|---------| +| **Concept** | Introductions, overviews, background information | Noun phrase | "SAP HANA Cloud", "OAuth 2.0 Authentication" | Explains what something is, why it matters, how it works | +| **Reference** | API documentation, tables, specifications, syntax | Noun phrase | "SAP HANA Cloud JavaScript Reference", "API Endpoints" | Lists methods, parameters, configuration options | +| **Complex Task** | Tutorials, multi-step procedures with code | Gerund phrase (-ing) | "Developing SAP HANA Cloud Applications", "Building a Fiori App" | Step-by-step tutorials with code samples | +| **Detailed Task** | Single tasks with code samples | Gerund phrase (-ing) | "Creating an Application Project", "Configuring OAuth" | Specific how-to instructions | + +### Title Examples by Type + +**Concept Topics**: +- ✅ "API Authentication Overview" +- ✅ "Understanding OData Query Options" +- ✅ "SAP Cloud Platform Architecture" +- ❌ "How to Understand OAuth" (task format for concept) + +**Reference Topics**: +- ✅ "Environment Variables Reference" +- ✅ "Configuration Parameters" +- ✅ "Error Code Catalog" +- ❌ "Configuring Environment Variables" (task format for reference) + +**Task Topics**: +- ✅ "Implementing OAuth 2.0 Authentication" +- ✅ "Creating Your First API Request" +- ✅ "Deploying to Cloud Foundry" +- ❌ "OAuth Implementation" (noun phrase for task) + +--- + +## Content Selection Guidelines + +### Collaborate with Product Owners + +**Key Principle**: "Don't try to cover all of the APIs in your product." + +Work with product teams to: +1. **Identify Priority APIs**: Focus on most commonly used or business-critical APIs +2. **Define Key Use Cases**: Document typical scenarios, not every possibility +3. **Target Audience Needs**: Write for your primary developer persona +4. **Balance Coverage vs. Depth**: Deep coverage of important topics beats shallow coverage of everything + +### Content Scope Decisions + +#### Include: +- ✅ Customer-relevant information +- ✅ Business scenarios and use cases +- ✅ Integration patterns and workflows +- ✅ Authentication and security guidance +- ✅ Error handling patterns +- ✅ Performance best practices +- ✅ Migration guides for version changes + +#### Exclude: +- ❌ Internal implementation details +- ❌ Duplicate SAP API Business Hub information +- ❌ Every possible API method (focus on common ones) +- ❌ Internal architecture not relevant to consumers +- ❌ Debugging information for SAP internal teams + +### Depth vs. Breadth + +**Guideline**: "Don't write a novel, keep the topics short and concise." + +- **Short Topics**: 300-800 words for most topics +- **Long Tutorials**: 1000-2000 words maximum +- **Complex Topics**: Break into smaller, manageable subtopics +- **Progressive Disclosure**: Link to detailed information rather than including everything + +### Diagram Guidelines + +**Use Clear Diagrams**: +- Avoid excessive complexity +- Remove internal-only information +- Adapt internal architectural diagrams for external audiences +- Focus on customer-relevant flows and interactions + +**Avoid Redundancy**: +- Don't duplicate diagrams unnecessarily +- Use one clear diagram instead of multiple similar ones +- Reference existing diagrams when appropriate + +--- + +## Code Sample Standards + +### Quality Requirements + +All code samples must meet these criteria: + +#### 1. Compilable Without Errors + +**Requirement**: "Must compile without errors" + +- Test all code before publication +- Verify with actual compiler/interpreter +- Include necessary imports and dependencies +- Handle version-specific syntax + +**Bad Example** ❌: +```java +// This won't compile - missing imports +Customer customer = getCustomer(); +``` + +**Good Example** ✅: +```java +import com.sap.customer.Customer; +import com.sap.customer.CustomerService; + +CustomerService service = new CustomerService(); +Customer customer = service.getCustomer("12345"); +``` + +#### 2. Concise and Focused + +**Requirement**: "Concise, containing only API-relevant code" + +- Show only code necessary to demonstrate the concept +- Remove boilerplate unrelated to the API +- Focus on the API call itself and essential context + +**Bad Example** ❌: +```java +public class CustomerExample { + private static final Logger logger = LogManager.getLogger(); + private Configuration config; + private MetricsCollector metrics; + + public CustomerExample() { + this.config = new Configuration(); + this.metrics = new MetricsCollector(); + logger.info("Initializing example..."); + } + + public void demonstrateAPI() { + logger.debug("Starting API call"); + metrics.startTimer(); + try { + // Actual API usage buried in boilerplate + Customer customer = api.getCustomer("12345"); + logger.debug("Customer retrieved: " + customer.getName()); + } catch (Exception e) { + logger.error("Failed", e); + metrics.recordError(); + } finally { + metrics.stopTimer(); + } + } +} +``` + +**Good Example** ✅: +```java +// Get a customer by ID +Customer customer = api.getCustomer("12345"); +System.out.println("Customer: " + customer.getName()); + +// Error handling +try { + customer = api.getCustomer("invalid"); +} catch (NotFoundException e) { + System.out.println("Customer not found"); +} +``` + +#### 3. Sufficient Comments + +**Requirement**: "Include sufficient comments for clarity" + +- Explain **why**, not just **what** +- Comment complex logic or API-specific requirements +- Don't over-comment obvious code + +**Bad Example** ❌: +```java +// Create customer service +CustomerService service = new CustomerService(); +// Get customer +Customer customer = service.getCustomer("12345"); +// Print customer name +System.out.println(customer.getName()); +``` + +**Good Example** ✅: +```java +// Initialize service with default authentication +CustomerService service = new CustomerService(); + +// Retrieve customer by SAP customer number +// Note: Customer ID must be numeric string format +Customer customer = service.getCustomer("12345"); + +// Display full legal name (formatted by locale) +System.out.println(customer.getName()); +``` + +#### 4. Easy Copy-Paste + +**Requirement**: "Enable easy copy-paste into code editors" + +- Use standard formatting (not proprietary) +- Include necessary context (imports, variables) +- Avoid line breaks in strings when possible +- Use consistent indentation + +**Bad Example** ❌: +```java +Customer customer = api. + getCustomer( + "12345" + ); // Awkward formatting +``` + +**Good Example** ✅: +```java +Customer customer = api.getCustomer("12345"); +``` + +### Code Sample Patterns + +#### Pattern 1: Basic API Call + +```javascript +// Simple GET request example +const response = await fetch('[https://api.sap.com/customers/12345',](https://api.sap.com/customers/12345',) { + headers: { + 'Authorization': 'Bearer YOUR_TOKEN', + 'Content-Type': 'application/json' + } +}); + +const customer = await response.json(); +console.log(customer); +``` + +#### Pattern 2: Error Handling + +```java +try { + Customer customer = service.getCustomer(customerId); + processCustomer(customer); +} catch (NotFoundException e) { + // Customer doesn't exist - handle gracefully + logger.warn("Customer not found: " + customerId); + return Optional.empty(); +} catch (UnauthorizedException e) { + // Authentication failed - refresh token + refreshAuthToken(); + return getCustomerWithRetry(customerId); +} +``` + +#### Pattern 3: Complete Workflow + +```python +# Complete workflow: Authenticate, retrieve, update customer + +# Step 1: Authenticate +auth_token = authenticate(api_key, secret) + +# Step 2: Retrieve customer data +customer = api.get_customer( + customer_id="12345", + auth_token=auth_token +) + +# Step 3: Update customer information +customer['email'] = 'new.email@example.com' + +# Step 4: Save changes +result = api.update_customer( + customer_id="12345", + data=customer, + auth_token=auth_token +) + +print(f"Update successful: {result['status']}") +``` + +--- + +## Best Practices + +### 1. Progressive Learning + +Structure content for developers at different skill levels: + +**Beginner Level**: +- Quick start guides +- Simple, complete examples +- Step-by-step tutorials +- Heavy use of code samples + +**Intermediate Level**: +- Common integration patterns +- Best practices +- Error handling strategies +- Performance optimization + +**Advanced Level**: +- Complex workflows +- Custom extensions +- Advanced configuration +- Architecture patterns + +### 2. Practical Focus + +**Emphasize**: +- Real-world scenarios +- Working code examples +- Common pitfalls and solutions +- Typical workflows + +**De-emphasize**: +- Theoretical concepts without application +- Every possible parameter combination +- Rarely-used features +- Internal implementation details + +### 3. Tutorial Format for Complex Tasks + +For complex multi-step processes: + +1. **Break into Smaller Subtopics**: Each subtopic covers one logical step +2. **Clear Prerequisites**: State what readers need before starting +3. **Expected Outcomes**: Show what success looks like +4. **Troubleshooting**: Include common issues and solutions + +**Example Structure**: +``` +Tutorial: Building Your First Fiori Application +├── Prerequisites +│ ├── Required tools +│ ├── Account setup +│ └── Sample data +├── Part 1: Creating the Project +│ ├── Initialize project +│ ├── Configure manifest +│ └── Verify setup +├── Part 2: Building the UI +│ ├── Create view +│ ├── Add controls +│ └── Test locally +├── Part 3: Adding Data Binding +│ ├── Configure OData service +│ ├── Bind to controls +│ └── Test with real data +├── Part 4: Deployment +│ ├── Build for production +│ ├── Deploy to Cloud +│ └── Verify deployment +└── Troubleshooting + ├── Common build errors + ├── Connection issues + └── Getting help +``` + +### 4. Avoid Duplication with API Business Hub + +**Don't Duplicate**: +- ❌ API endpoint listings (available in API Business Hub) +- ❌ Parameter descriptions (auto-generated) +- ❌ Response schema definitions + +**Do Provide**: +- ✅ Deeper analysis of when to use which endpoint +- ✅ Integration patterns combining multiple endpoints +- ✅ Business context for API usage +- ✅ Migration guides and version comparisons + +### 5. Maintain and Update + +- **Regular Reviews**: Update guides when APIs change +- **Version Notices**: Clearly indicate which API version guide applies to +- **Deprecation Warnings**: Mark outdated content prominently +- **Feedback Loops**: Collect and incorporate developer feedback + +--- + +## Examples + +### Example 1: Concept Topic + +**Title**: "Understanding SAP OAuth 2.0 Authentication" + +**Structure**: +```markdown +# Understanding SAP OAuth 2.0 Authentication + +## What is OAuth 2.0? + +OAuth 2.0 is an authorization framework that enables applications +to obtain limited access to user accounts on SAP services. + +## Why Use OAuth 2.0? + +- **Security**: Never expose user passwords to third-party applications +- **Limited Access**: Grant specific permissions, not full account access +- **Revocable**: Users can revoke access anytime +- **Standard**: Industry-standard protocol supported across SAP services + +## How It Works + +[Diagram: OAuth 2.0 Flow] + +1. Application requests authorization +2. User grants permission +3. Application receives access token +4. Application uses token to access resources + +## Grant Types + +SAP supports three OAuth 2.0 grant types: + +### Authorization Code (Recommended) +Best for server-side web applications... + +### Client Credentials +Best for machine-to-machine communication... + +### Refresh Token +Used to obtain new access tokens... + +## Next Steps + +- [Implementing OAuth 2.0 Authentication](#) (Task Guide) +- [OAuth Configuration Reference](#) (Reference) +``` + +### Example 2: Task Topic + +**Title**: "Implementing OAuth 2.0 Client Credentials Flow" + +**Structure**: +```markdown +# Implementing OAuth 2.0 Client Credentials Flow + +This guide shows how to implement OAuth 2.0 authentication using +the Client Credentials grant type for server-to-server communication. + +## Prerequisites + +- SAP BTP account +- OAuth client ID and secret +- Node.js 14+ installed + +## Step 1: Obtain Client Credentials + +1. Log in to SAP BTP Cockpit +2. Navigate to Security → OAuth Clients +3. Click "Create New Client" +4. Copy client ID and secret + +## Step 2: Request Access Token + +```javascript +const fetch = require('node-fetch'); + +async function getAccessToken() { + const credentials = Buffer.from( + `${CLIENT_ID}:${CLIENT_SECRET}` + ).toString('base64'); + + const response = await fetch('[https://auth.sap.com/oauth/token',](https://auth.sap.com/oauth/token',) { + method: 'POST', + headers: { + 'Authorization': `Basic ${credentials}`, + 'Content-Type': 'application/x-www-form-urlencoded' + }, + body: 'grant_type=client_credentials&scope=read write' + }); + + const data = await response.json(); + return data.access_token; +} +``` + +## Step 3: Use Token for API Requests + +```javascript +async function callAPI() { + const token = await getAccessToken(); + + const response = await fetch('[https://api.sap.com/resource',](https://api.sap.com/resource',) { + headers: { + 'Authorization': `Bearer ${token}` + } + }); + + return await response.json(); +} +``` + +## Step 4: Handle Token Expiration + +Tokens expire after 1 hour. Implement token refresh: + +```javascript +let cachedToken = null; +let tokenExpiry = null; + +async function getValidToken() { + const now = Date.now(); + + // Return cached token if still valid + if (cachedToken && tokenExpiry > now) { + return cachedToken; + } + + // Request new token + cachedToken = await getAccessToken(); + tokenExpiry = now + (3600 * 1000); // 1 hour + + return cachedToken; +} +``` + +## Troubleshooting + +### "Invalid client credentials" +- Verify client ID and secret are correct +- Ensure credentials are base64 encoded properly + +### "Insufficient scope" +- Check that your OAuth client has required scopes +- Request appropriate scopes in token request + +## Next Steps + +- [OAuth 2.0 Best Practices](#) +- [Authorization Code Flow](#) +- [Token Management Strategies](#) +``` + +### Example 3: Reference Topic + +**Title**: "OAuth Configuration Parameters" + +**Structure**: +```markdown +# OAuth Configuration Parameters + +Complete reference for OAuth 2.0 configuration options. + +## Token Endpoint + +**URL**: `[https://auth.sap.com/oauth/token`](https://auth.sap.com/oauth/token`) + +## Request Parameters + +| Parameter | Required | Description | Example | +|-----------|----------|-------------|---------| +| `grant_type` | Yes | OAuth grant type | `client_credentials` | +| `client_id` | Yes | OAuth client identifier | `sb-client-12345` | +| `client_secret` | Yes | OAuth client secret | `abc123...` | +| `scope` | No | Requested permissions | `read write` | + +## Response Format + +```json +{ + "access_token": "eyJhbGc...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read write" +} +``` + +## Error Codes + +| Code | Description | Resolution | +|------|-------------|------------| +| `invalid_client` | Invalid credentials | Verify client ID/secret | +| `invalid_grant` | Grant type not supported | Use supported grant type | +| `invalid_scope` | Scope not available | Request valid scopes | +``` + +--- + +## Reference + +### SAP Resources + +- **SAP Help Portal**: [https://help.sap.com/](https://help.sap.com/) +- **SAP API Business Hub**: [https://api.sap.com/](https://api.sap.com/) +- **SAP Community**: [https://community.sap.com/](https://community.sap.com/) + +### Related Documentation + +- API Reference Documentation Standards +- API Quality Checklist +- Code Sample Guidelines + +--- + +**Document Version**: 1.0.0 +**Last Updated**: 2025-11-21 +**Maintainer**: SAP Skills Team | [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills) diff --git a/references/glossary-resources.md b/references/glossary-resources.md new file mode 100644 index 0000000..f4fb205 --- /dev/null +++ b/references/glossary-resources.md @@ -0,0 +1,472 @@ +# Glossary and External Resources + +**Source**: [https://github.com/SAP-docs/api-style-guide/](https://github.com/SAP-docs/api-style-guide/) +**Last Verified**: 2025-11-21 + +**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)) + +**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates. + +--- + +## Table of Contents + +1. [Glossary](#glossary) +2. [External Resources](#external-resources) +3. [SAP-Specific Resources](#sap-specific-resources) +4. [Quick Reference](#quick-reference) + +--- + +## Glossary + +### A + +**API (Application Programming Interface)** +An interface provided by an application for interacting with other applications. Enables software programs to exchange information across organizational boundaries by selectively exposing functionality. + +**API Documentation Comment** +Combines descriptions and block tags in source code for generating API reference documentation. Used by documentation generators like Javadoc, JSDoc, and Doxygen. + +**API Documentation Generators** +Tools like Javadoc, JSDoc, Doxygen, and Swagger that extract comments from source code and produce structured documentation. + +### C + +**Code Sample File** +A complete, working example demonstrating API features that ships with SDKs. More comprehensive than code snippets, showing real-world implementation patterns. + +**Code Snippet** +Several lines of code illustrating API method usage. Typically embedded in documentation to demonstrate specific functionality. + +**Component (OpenAPI)** +Reusable object definitions in OpenAPI Specification 3.0+ (called "Definitions" in version 2.0). Includes schemas, parameters, responses, examples, etc. + +### D + +**Decommissioned** +APIs that have been fully retired and cannot be used in production. Final state in API lifecycle. + +**Definition (OpenAPI)** +See **Component**. Term used in OpenAPI Specification 2.0 for reusable objects. + +**Demo Application** +A basic implementation provided with SDKs showing main API capabilities and typical usage patterns. + +**Deprecated** +API elements no longer supported in future releases, marked with the `x-sap-stateInfo` attribute or `@deprecated` tag. Not encouraged for use but still functional. + +**Documentation Tag** +Special marker instructing documentation generators how to format comment sections. Examples: `@param`, `@return`, ``, `\file`. + +### E + +**Entity (OData)** +Typed data object in OData Entity Data Model (EDM). Examples: Customer, Employee, Order. + +**Entity Data Model (EDM)** +Structured data description in OData protocol defining entities, entity sets, relationships, and operations. + +**Entity Set (OData)** +Named collection of entities. Example: "Customers" is an entity set containing Customer entities. + +**Exception** +Documented errors occurring during method execution, typically using `@throws`, `@exception`, or `` tags. + +### M + +**Metadata (OData)** +XML document describing the structure of an OData service. Accessible at `$metadata` endpoint (e.g., `[https://api.sap.com/odata/$metadata](https://api.sap.com/odata/$metadata)`). + +### O + +**OData (Open Data Protocol)** +A REST-based protocol for querying and updating data, built on HTTP, Atom/XML, and JSON standards. Maintained by OASIS Open. + +**Operation (REST/OData)** +HTTP method (GET, PUT, POST, DELETE, PATCH) for manipulating endpoints or performing actions on resources. + +**OpenAPI Specification** +Community-driven open specification for RESTful APIs under the OpenAPI Initiative. Version 3.0.3 is current standard. + +### P + +**Parameter** +Option passed with a path, such as filtering criteria, sorting options, or pagination controls. Can appear in path, query, header, body, or formData. + +**Partner APIs** +APIs created by SAP partners for customers, published on the SAP API Business Hub. + +**Path (REST/OData)** +Endpoint or resource in API URLs. Examples: `/users`, `/users/{id}`, `/orders/{orderId}/items`. + +**Private APIs** +APIs restricting access to vendors, partners, or selected customers. Not publicly available. + +**Public APIs** +APIs available in the public domain that become vendor-client contracts. Require careful versioning and deprecation management. + +### R + +**Resource (REST/OData)** +Concept or object that users want to control through HTTP requests. Identified by URIs and manipulated using HTTP methods. + +**Response** +HTTP status code combined with outcome description, optionally including response body with data or error information. + +**REST API (Representational State Transfer)** +Architectural style enabling cross-platform CRUD operations over HTTP. Focuses on resources rather than actions. + +**Return Type/Value** +Data returned by methods, documented using `@return`, `@returns`, or `` tags. + +### S + +**Schema (OpenAPI)** +Data structure definition describing request/response formats. Defines properties, types, required fields, and validation rules. + +**SPI (Service Provider Interface)** +Vendor-defined interface intended for third-party implementation, extending or customizing API functionality. + +### X + +**x-sap-stateInfo** +SAP-specific OpenAPI extension attribute defining API lifecycle state: beta, active, deprecated, or decommissioned. + +--- + +## External Resources + +### API Standards & Specifications + +#### OpenAPI Specification + +**URL**: [https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html) + +**Description**: The standard for RESTful APIs. A community-driven open specification within the OpenAPI Initiative for describing HTTP APIs in a machine-readable format. + +**Use For**: +- REST API specification structure +- OpenAPI document format +- API schema definitions +- Operation documentation + +**Current Version**: 3.0.3 (3.1.0 available) + +#### OData Specification + +**URL**: [https://www.odata.org/documentation/](https://www.odata.org/documentation/) + +**Description**: The standard for OData maintained by OASIS Open. Defines protocol for querying and updating data over HTTP. + +**Use For**: +- OData service structure +- EDM (Entity Data Model) design +- Query operation syntax +- OData conventions + +**Supported Versions**: 4.01, 3.0, 2.0 + +### Documentation Tools + +#### Java - Javadoc + +**URL**: [https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) + +**Description**: Oracle's guidance on "How to Write Doc Comments for the Javadoc Tool" through their Technology Network. + +**Use For**: +- Java API documentation +- Javadoc tag reference +- Documentation comment format +- Tool usage and configuration + +**Official Oracle Reference**: [https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html) + +#### JavaScript - JSDoc + +**URL**: [https://jsdoc.app/](https://jsdoc.app/) + +**Description**: JSDoc 3 documentation generator available on GitHub. Comprehensive tag reference and examples. + +**Use For**: +- JavaScript API documentation +- JSDoc tag syntax +- TypeScript documentation +- Node.js project documentation + +**Tag Reference**: [https://jsdoc.app/index.html#block-tags](https://jsdoc.app/index.html#block-tags) + +**Markdown Support**: [https://jsdoc.app/about-including-markdown.html](https://jsdoc.app/about-including-markdown.html) + +#### Microsoft .NET + +**C# XML Documentation** +**URL**: [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) + +**Description**: Microsoft's official guidance for C# XML documentation comments. + +**Use For**: +- .NET API documentation +- XML comment syntax +- Visual Studio integration +- IntelliSense support + +**.NET Naming Guidelines** +**URL**: [https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines) + +**Description**: Microsoft's official naming conventions for .NET libraries. + +**Use For**: +- .NET naming standards +- PascalCase/camelCase usage +- Namespace organization +- Framework design guidelines + +#### C/C++ - Doxygen + +**URL**: [https://www.doxygen.nl/](https://www.doxygen.nl/) + +**Description**: Documentation generator supporting multiple languages including C++, C#, PHP, Java, and Python. + +**Use For**: +- C/C++ API documentation +- Multi-language documentation +- Diagram generation +- Cross-platform documentation + +**Manual**: [https://www.doxygen.nl/manual/](https://www.doxygen.nl/manual/) + +#### Python - Sphinx + +**URL**: [https://www.sphinx-doc.org/](https://www.sphinx-doc.org/) + +**Description**: Documentation generator for Python with reStructuredText support. + +**Use For**: +- Python API documentation +- Python package documentation +- Technical documentation +- ReadTheDocs integration + +### SAP-Specific Resources + +#### SAP API Business Hub + +**URL**: [https://api.sap.com/](https://api.sap.com/) + +**Description**: Central repository for SAP's REST and OData API references. Provides interactive API exploration, testing, and documentation. + +**Use For**: +- Publishing REST/OData APIs +- Discovering SAP APIs +- Testing API endpoints +- Downloading API specifications + +**Login Required**: SAP account needed for full access + +#### SAP Help Portal + +**URL**: [https://help.sap.com/](https://help.sap.com/) + +**Description**: Comprehensive SAP product documentation and help resources. + +**Use For**: +- Product documentation +- Technical guides +- Configuration guides +- Release notes + +#### SAP Developer Center + +**URL**: [https://developers.sap.com/](https://developers.sap.com/) + +**Description**: Resources for SAP developers including tutorials, code samples, and developer guides. + +**Use For**: +- Getting started tutorials +- Code samples +- Developer community +- Learning paths + +**Tutorial Navigator**: [https://developers.sap.com/tutorial-navigator.html](https://developers.sap.com/tutorial-navigator.html) + +#### SAP Community + +**URL**: [https://community.sap.com/](https://community.sap.com/) + +**Description**: SAP's community platform for asking questions, sharing knowledge, and connecting with other developers. + +**Use For**: +- Community support +- Best practices +- Code sharing +- Networking + +#### SAP Business Accelerator Hub (formerly API Business Hub) + +**URL**: [https://api.sap.com/](https://api.sap.com/) + +**Description**: Updated name for SAP API Business Hub. Provides APIs, events, and integrations. + +**Use For**: +- API discovery and exploration +- Integration content +- Pre-built integrations +- API package management + +--- + +## SAP-Specific Resources + +### SAP API Style Guide Repository + +**URL**: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide) + +**Description**: Official SAP API Style Guide source repository containing all documentation standards. + +**Contents**: +- API naming guidelines +- REST/OData documentation standards +- Java/JavaScript/.NET documentation +- Manual template guidelines +- Deprecation policy +- Quality processes + +**Last Updated**: 2021.01 + +**Clone Command**: +```bash +git clone [https://github.com/SAP-docs/api-style-guide.git](https://github.com/SAP-docs/api-style-guide.git) +``` + +### SAP BTP (Business Technology Platform) + +**Cockpit**: [https://cockpit.sap.com/](https://cockpit.sap.com/) + +**Documentation**: [https://help.sap.com/docs/BTP](https://help.sap.com/docs/BTP) + +**API Documentation**: Available through SAP API Business Hub + +### SAP Integration Suite + +**URL**: [https://help.sap.com/docs/INTEGRATION_SUITE](https://help.sap.com/docs/INTEGRATION_SUITE) + +**Includes**: +- API Management +- Integration Advisor +- Open Connectors +- API Designer (bundled with Integration Suite) + +**Use For**: +- Creating and managing APIs +- API design and development +- Integration patterns +- API lifecycle management + +### SAP NetWeaver + +**JavaScript API Example**: Available through SAP NetWeaver documentation + +**URL**: [https://help.sap.com/docs/SAP_NETWEAVER](https://help.sap.com/docs/SAP_NETWEAVER) + +**Use For**: +- JavaScript API patterns +- NetWeaver-specific documentation +- Portal development + +--- + +## Quick Reference + +### By Language/Technology + +| Language/Tech | Standard | Tool | Documentation | +|---------------|----------|------|---------------| +| **Java** | Javadoc | javadoc | [Oracle Javadoc](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) | +| **JavaScript** | JSDoc 3 | jsdoc | [JSDoc](https://jsdoc.app/) | +| **.NET (C#)** | XML Comments | DocFX, Sandcastle | [Microsoft XML Docs](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) | +| **C/C++** | Doxygen | doxygen | [Doxygen Manual](https://www.doxygen.nl/manual/) | +| **Python** | reStructuredText | Sphinx | [Sphinx](https://www.sphinx-doc.org/) | +| **REST** | OpenAPI | Swagger, Redoc | [OpenAPI Spec](https://spec.openapis.org/oas/latest.html) | +| **OData** | OData 4.01 | Various | [OData.org](https://www.odata.org/) | + +### By Documentation Type + +| Documentation Type | Primary Resource | Secondary Resource | +|-------------------|------------------|-------------------| +| **REST API Reference** | OpenAPI Spec | SAP API Business Hub | +| **OData API Reference** | OData Spec | SAP API Business Hub | +| **Java API Reference** | Javadoc Guide | SAP Naming Guidelines | +| **JavaScript API Reference** | JSDoc Guide | SAP Naming Guidelines | +| **.NET API Reference** | Microsoft XML Docs | SAP Naming Guidelines | +| **Developer Guides** | SAP Developer Center | SAP Help Portal | +| **Tutorials** | SAP Tutorial Navigator | SAP Community | +| **Code Samples** | SAP API Business Hub | GitHub | + +### By Task + +| Task | Resource | URL | +|------|----------|-----| +| **Find SAP APIs** | SAP API Business Hub | [https://api.sap.com/](https://api.sap.com/) | +| **Learn SAP Development** | SAP Developer Center | [https://developers.sap.com/](https://developers.sap.com/) | +| **Read Product Docs** | SAP Help Portal | [https://help.sap.com/](https://help.sap.com/) | +| **Ask Questions** | SAP Community | [https://community.sap.com/](https://community.sap.com/) | +| **Design REST APIs** | OpenAPI Spec | [https://spec.openapis.org/](https://spec.openapis.org/) | +| **Design OData APIs** | OData Spec | [https://www.odata.org/](https://www.odata.org/) | +| **Write Java Docs** | Javadoc Guide | [https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) | +| **Write JS Docs** | JSDoc Guide | [https://jsdoc.app/](https://jsdoc.app/) | +| **Write .NET Docs** | Microsoft Docs | [https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) | +| **Generate C++ Docs** | Doxygen | [https://www.doxygen.nl/](https://www.doxygen.nl/) | + +--- + +## Version Information + +### API Standard Versions + +| Standard | Current Version | Previous Versions | Status | +|----------|----------------|-------------------|--------| +| **OpenAPI** | 3.0.3 | 2.0 (Swagger), 3.1.0 | Active | +| **OData** | 4.01 | 4.0, 3.0, 2.0 | Active | +| **Javadoc** | Java 17 | Java 8, 11 | Active | +| **JSDoc** | 3.x | 2.x | Active | +| **.NET XML** | .NET 6+ | .NET Framework, .NET Core | Active | +| **Doxygen** | 1.9+ | 1.8.x | Active | + +### SAP API Style Guide Versions + +| Version | Date | Key Changes | +|---------|------|-------------| +| **2021.01** | January 2021 | API Designer clarification, expanded description guidelines | +| **Initial** | Earlier | Base standards established | + +--- + +## Related SAP Documentation + +### Official SAP Standards Documents + +1. **SAP API Style Guide** - This complete skill reference +2. **SAP Naming Conventions** - naming-conventions.md +3. **SAP Quality Processes** - quality-processes.md +4. **SAP Deprecation Policy** - deprecation-policy.md +5. **SAP Developer Guides** - developer-guides.md + +### SAP Cloud Documentation + +- **SAP BTP**: [https://help.sap.com/docs/BTP](https://help.sap.com/docs/BTP) +- **SAP Cloud Foundry**: [https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/](https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/) +- **SAP Kyma**: [https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/](https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/) + +### SAP Development Tools + +- **SAP Business Application Studio**: [https://help.sap.com/docs/BAS](https://help.sap.com/docs/BAS) +- **SAP Web IDE**: (Deprecated - migrating to Business Application Studio) +- **SAP HANA Cloud**: [https://help.sap.com/docs/HANA_CLOUD](https://help.sap.com/docs/HANA_CLOUD) + +--- + +**Document Version**: 1.0.0 +**Last Updated**: 2025-11-21 +**Maintainer**: SAP Skills Team | [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills) diff --git a/references/java-javascript-dotnet-guide.md b/references/java-javascript-dotnet-guide.md new file mode 100644 index 0000000..341bbc6 --- /dev/null +++ b/references/java-javascript-dotnet-guide.md @@ -0,0 +1,1517 @@ +# SAP API Style Guide - Complete Reference Documentation +## Java/JavaScript/.NET API Documentation (All 39 Files Consolidated) + +**Source**: [https://github.com/SAP-docs/api-style-guide/tree/main/docs/40-java-javascript-and-msnet](https://github.com/SAP-docs/api-style-guide/tree/main/docs/40-java-javascript-and-msnet) +**Last Verified**: 2025-11-21 + +**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)) + +**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates. + +**Comprehensive Reference**: All 39 markdown files extracted and organized + +--- + +## TABLE OF CONTENTS + +1. [Overview & Core Principles](#overview--core-principles) +2. [Documentation Comments Structure](#documentation-comments-structure) +3. [Java API Documentation Templates](#java-api-documentation-templates) +4. [Java & JavaScript Common Tags](#java--javascript-common-tags) +5. [JavaScript-Specific Tags](#javascript-specific-tags) +6. [.NET Documentation Tags](#net-documentation-tags) +7. [C/C++ Documentation Tags](#cc-documentation-tags) +8. [HTML Tags for Documentation](#html-tags-for-documentation) +9. [Best Practices & Guidelines](#best-practices--guidelines) +10. [Language-Specific Syntax](#language-specific-syntax) + +--- + +## OVERVIEW & CORE PRINCIPLES + +### Purpose of API Reference Documentation +- Auto-generates API reference documentation from source code in Java, JavaScript, and Microsoft .NET +- Standardizes how developers document code elements to enable professional, consistent API documentation +- Three essential areas covered: + 1. **Documentation Comments** - Write according to specific rules + 2. **Documentation Tags** - Recognized by API documentation generators + 3. **Language-Specific Templates** - Standardized approaches for different languages + +### Key Architectural Principles +- Object-oriented languages (Java, JavaScript, .NET, C/C++) share common API structural elements +- Documentation is extracted from source code comments rather than maintained separately +- Consistency across implementation ensures high-quality automated documentation generation + +--- + +## DOCUMENTATION COMMENTS STRUCTURE + +### General Structure Components +All documentation comments consist of two main components: +1. **Description** - Mandatory explanation of the code element +2. **Block Tags** - Special markers used by generation tools to structure output + +### Language-Specific Comment Formats + +#### Java and JavaScript +- Use specific comment syntax with delimiters +- Format: `/** ... */` +- Designated tag areas follow the description + +#### .NET +- Supports XML-based documentation comments +- Alternative: External XML files using the `` tag +- Format: `/// content` + +### Placement Rules +- Place documentation comments **before** declarations of: + - Namespaces + - Classes + - Interfaces + - Class/interface members + +### Mandatory vs. Optional +- **Description**: Mandatory when documenting classes, interfaces, class members, or interface members +- **Block Tags**: Used to provide structured metadata; many are optional + +--- + +## JAVA API DOCUMENTATION TEMPLATES + +### Template Categories (6 Primary Types) + +#### 1. Overview Page Template +**Purpose**: Documents groups of packages; provides cover sheet for API documentation + +**For Java APIs - Create `overview.html`**: +- Purpose of the API +- Main features in list format +- Package overview +- Links to external resources + +**For JavaScript APIs - Create `readme.md`**: +- Clear title +- Brief description of functionality +- Bulleted links to major API components + +**Key Recommendations**: +- Opening sentence should summarize API concisely +- Address: What problems does it solve? What are primary capabilities? How are packages organized? +- Include external references to guides, diagrams, help portals +- Optional but recommended addition + +#### 2. Package Pages Template +**Purpose**: Documents individual Java packages using `package.html` file + +**Mandatory Requirements**: +- "It is mandatory to use this file" +- Must be placed at appropriate folder level in source code + +**Required Content Elements**: +1. **Purpose Statement** - Explain what package does +2. **Content Overview** - Describe grouped Java source files +3. **Background Information** - Provide context for understanding and usage +4. **Class Relationships** - Clarify connections between classes + +**Format Guidelines**: +- Begin with summary sentence (doc comment format) +- Use HTML structure (DOCTYPE, head, body tags) +- Organize with paragraphs and lists +- Present progressively from general to specific + +#### 3. Interface and Class Template +**Opening Statement Requirements**: +- Begin with imperative verb: "Allows you," "Enables you" +- OR use third-person singular indicative form +- Follow opening with supplementary details on subsequent lines +- Include background context and special considerations + +**Two Documentation Approaches**: + +**A) Classic API Format** +- Used for third-party developer applications +- Opening describes what interface "Represents/Contains/Provides/Defines" +- Example: "Allows you to manage connections in Data Access Layer internal connection pool" +- Follow with: "Provides basic methods to manage connections in context of use..." + +**B) Service Provider Interface (SPI) Format** +- Designed for platform implementation (not direct developer use) +- Opening directs implementers to "Implement a service for" or "Provide an implementation of" +- Guide developers on implementation responsibility +- Simpler, more direct approach than Classic API + +**Documentation Structure Elements**: +- Initial statement (verb or noun phrase) +- Supplementary information block +- Relevant cross-references (@see tags) +- Implementation requirements (for SPIs) + +#### 4. Method Template +**Core Requirements**: +- "Background information needed to understand and use this method" +- "Special considerations that apply to this method" +- Description: mandatory first sentence plus optional additional content +- Block tags in specified order + +**Standard Verb Usage by Method Type**: + +| Method Type | Recommended Verb | Example | +|---|---|---| +| Constructor | Constructs | "Constructs a connection object" | +| Boolean | Indicates (whether...) | "Indicates whether the object can be used" | +| Getter | Returns/Retrieves/Gets | "Returns the connection parameter" | +| Setter | Defines/Sets | "Defines the connection timeout" | +| Other | Adds/Removes/Creates/Releases/[applicable verb] | "Creates a new database connection" | + +**Block Tag Order**: +``` +@param +@return +@throws +@see +@since +@deprecated +``` + +**Key Best Practices**: +1. **Default Values**: Setter descriptions should mention default property values +2. **Constructor Defaults**: Reference defaults if applicable +3. **Code Examples**: Use `
` HTML tags within paragraph tags for code snippets
+4. **Parameter Descriptions**: Format as "A(n) `type` object/value that [describes purpose]"
+5. **Cross-References**: Use `@see` tags to link related methods (pair getters with setters)
+6. **Parameter Order**: Document in same sequence as method signature
+
+#### 5. Enum Template
+**Enum-Level Documentation**:
+- Start with "Provides..." or "An enumeration that provides..."
+- Include background information needed for understanding and usage
+- Note any special considerations applying to enum and its values
+
+**Enum Value Documentation**:
+- Begin with third-person singular verbs (e.g., "Allows," "Provides")
+- OR use noun phrases
+- Provide second line with additional context explaining behavior triggered by that value
+- Single-line format using `/** Description */` is acceptable for brevity
+
+**Documentation Styles**:
+1. **Multi-line format**: Detailed explanations with `
` tags for paragraph breaks
+2. **Single-line format**: Concise, straightforward descriptions
+
+**Practical Example - SecurityStatus Enum**:
+```
+/**
+ * Provides the statuses that can apply to a business security profile...
+ */
+public enum SecurityStatus {
+    /**
+     * Specifies that all elements are [action] in a business security profile setting
+     */
+    ELEMENT_STATUS
+}
+```
+
+#### 6. Constant Template
+**Starting the Description**:
+- Begin with action verb in third-person singular form: "Specifies," "Defines," "Is"
+- OR use noun phrase
+
+**Information to Include**:
+- "Background information needed to understand and use this constant"
+- "Special considerations that apply to this constant"
+
+**Syntax Options**:
+
+**Multi-line Format (Recommended)**:
+```java
+/**
+ * [Verb/Noun phrase describing the constant]
+ * 
Additional context or important notes

+ */
+public static final constant_type constant_name = constant_value;
+```
+
+**Single-line Format (For Simple Constants)**:
+```java
+/** [Brief description of the constant] */
+public static final constant_type constant_name = constant_value;
+```
+
+**Practical Examples**:
+- Password constant: "The password used to log in to the CMS. This password must not contain any spaces."
+- Simple constant: "The year of the date"
+
+---
+
+## JAVA & JAVASCRIPT COMMON TAGS
+
+### Tag Organization Requirements
+
+**Quality Standards**:
+- "Always add value to your comment"
+- Maintain consistency in tag ordering across documentation
+- Tags are case-sensitive; block tag comments begin with uppercase letters
+
+**Structural Rules**:
+- Multiple instances of certain tags (like `@param`) allowed
+- Some tags (like `@return`) appear only once
+- "Group multiple block tags of the same type together"
+- Avoid ending single-sentence tag comments with periods
+- Don't duplicate automatically-generated information
+
+**Recommended Tag Sequence** (Standard Order):
+```
+@param
+@return
+@throws
+@see
+@since
+@deprecated
+@version
+```
+
+### Comprehensive Tag Reference
+
+#### @param Tag
+**Purpose**: Documents method and function parameters
+
+**Mandatory**: Yes - for every parameter in method and constructor descriptions
+
+**Java Syntax**:
+```java
+@param parameter-name parameter-description
+```
+
+**JavaScript Syntax**:
+```javascript
+@param {type} parameter-name description
+@param {type} [optional-name] description
+@param {type1|type2} parameter-name description for union types
+```
+
+**Key Guidelines**:
+- Use noun phrase to describe the value represented by the parameter
+- Java: first letter lowercase, no hyphen before description
+- JavaScript: first letter uppercase
+- No periods at the end
+- Document in signature order
+- JavaScript: Mark optional parameters with square brackets `[parameter-name]`
+- JavaScript: Multiple types using pipe separator `{type1|type2}`
+- JavaScript: Use `{*}` for arbitrary types
+- Describe defaults and possible values
+
+**Practical Examples**:
+```javascript
+@param {String} url An absolute URL of the image
+@param {Number} width The image width in pixels
+@param {Number} [height] The image height in pixels (optional, defaults to width)
+@param {String|Array} data Data to process - can be string or array
+```
+
+#### @return / @returns Tag
+**Purpose**: Describes what a method or function returns
+
+**Mandatory**: Yes - for all methods except constructors and void-returning methods
+
+**Java Syntax**:
+```java
+@return description
+```
+
+**JavaScript Syntax**:
+```javascript
+@return {type1|type2|...} description
+```
+
+**Key Guidelines**:
+- Start descriptions with noun phrase
+- Begin with capital letter; avoid hyphens at start
+- Do not conclude with a period
+- Document all possible return scenarios, particularly `null` or Boolean values
+- Java: wrap result name with `...` (object name, returned type, `null`, or Boolean value)
+- JavaScript: Document multiple return types using `{type1|type2|...}` notation
+- JavaScript: description is optional
+
+**Example Patterns**:
+```java
+@return An int specifying the server port
+@return true if the object can be used, false otherwise
+```
+
+```javascript
+@return {db.ResultSet} The result set from the query
+@return {String|Null} The configuration value or null if not found
+```
+
+#### @throws Tag
+**Purpose**: Documents exceptions that methods may throw
+
+**Mandatory**: Yes - for every exception a method can throw
+
+**Java Syntax**:
+```java
+@throws type description
+```
+
+**JavaScript Syntax**:
+```javascript
+@throws {type} description
+```
+
+**Key Guidelines**:
+- Describe exceptions using complete noun phrases as standard sentences
+- Begin descriptions with capitalized words, avoiding hyphens at start
+- Order multiple exceptions alphabetically by their names
+- JavaScript: type parameter is optional (unlike Java)
+- "You must have one tag for every exception" that method declares or throws
+
+**Practical Examples**:
+```java
+@throws SDKException If an error occurs during the connection update
+@throws NullPointerException If parameter name is null
+@throws IllegalArgumentException If value exceeds maximum bounds
+```
+
+```javascript
+@throws {$.db.SQLException} Throws an error on invalid parameter
+@throws {Error} If connection is not established
+```
+
+#### @see Tag
+**Purpose**: Creates references in "See Also" section; supports plain text, URLs, or labeled links
+
+**Java Syntax Options**:
+- Constants: `@see #constant`
+- Constructors: `@see #constructor(Type, Type,...)`
+- Methods: `@see #method(Type, Type,...)`
+- Classes (qualified or unqualified): `@see ClassName` or `@see package.ClassName`
+- Packages: `@see package`
+- Plain text: `@see "free text"`
+- Hyperlinks: `@see text`
+- With optional label: `@see class-reference label`
+
+**JavaScript Syntax Options**:
+- Simple path: `@see setObject`
+- With link tag: `@see {@link setObject} for more information`
+- External URL: `@see {@link [http://sap.help.com|the](http://sap.help.com|the) SAP Help Portal}`
+
+**Key Guidelines**:
+- Use double quotes for plain text references in Java
+- JavaScript: paths automatically generate hyperlinks
+- JavaScript: Use `@link` tag for free text hyperlinks
+- Apply sparingly to keep comment readable
+- Add where it adds value, only for first occurrence of API names
+- Order from least to fully-qualified signatures (constants → packages)
+
+**Practical Examples**:
+```java
+@see Table
+@see Table#getColumns()
+@see TableColumn#setDataType(TableDataType) setDataType
+@see com.example.api.Connection
+```
+
+```javascript
+@see setObject
+@see {@link setObject} for more information
+@see {@link [http://sap.help.com|the](http://sap.help.com|the) SAP Help Portal}
+```
+
+#### @deprecated Tag
+**Purpose**: Marks classes, interfaces, or members as no longer recommended for use
+
+**Mandatory**: Block tag - must never be left blank
+
+**Required Syntax Structure**:
+```
+@deprecated As of version NN, replaced by {@link class_name}
+```
+
+**Key Guidelines**:
+1. **Version Information**: Start with "As of" followed by specific API version when deprecation occurred
+2. **Replacement Reference**: Include "replaced by" with `@link` tag pointing to successor
+3. **Additional Context**: May provide supplementary details about deprecation
+4. Avoid specifying exact decommissioning timelines
+
+**Practical Example**:
+```java
+/**
+ * Returns the SELECT clause of a SQL query.
+ *
+ * @return A String that contains the SELECT clause
+ * @deprecated As of version 2.4, replaced by {@link NewClass#getSelect()}
+ * 
{@link #getNewClass()} allows you to retrieve a {@link NewClass} object.

+ */
+String getSelect();
+```
+
+#### @since Tag
+**Purpose**: Indicates API version when class, interface, or member was introduced or modified
+
+**Syntax**:
+```
+@since version-number
+```
+
+**Key Characteristics**:
+- Optional tag
+- Used within JavaDoc-style comments
+- Specifies version number when functionality became available
+- Helps developers understand compatibility requirements
+- Commonly applied to methods, classes, and interfaces
+- Supports semantic versioning (e.g., 14.0.5)
+
+**Practical Example**:
+```java
+/**
+ * Returns the connection parameter.
+ *
+ * @param name a String that represents the connection parameter name
+ * @since 14.0.5
+ */
+ConnectionParameter getParameter(String name);
+```
+
+#### @version Tag
+**Purpose**: Marks internal version of a class or interface
+
+**Syntax**:
+```
+@version version-number
+```
+
+**Key Characteristics**:
+- Optional element
+- Internal use only - NOT rendered in API documentation outputs
+- Useful for tracking internal version history without exposing metadata
+- Supports standard versioning schemes (e.g., semantic versioning like "14.1.2")
+
+**Practical Example**:
+```java
+/**
+ * Gets the column description.
+ *
+ * @return A string that represents the description of the table column
+ * @version 14.1.2
+ */
+String GetDescription();
+```
+
+### Inline Java Tags (Embedded in Comments)
+
+#### {​@code text}
+- Renders text in code font
+- Prevents HTML markup and nested Javadoc tag interpretation
+- Enables regular angle brackets instead of HTML entities
+
+#### {​@docRoot}
+- Provides relative path from any generated page to documentation root
+- Useful for referencing shared files across all pages
+
+#### {​@inheritDoc}
+- Copies documentation from parent classes or interfaces
+- Inserts at tag's location in current comment
+
+#### {​@link}
+- Creates hyperlinks to package, class, interface, or member documentation
+- Displays visible text labels in code font
+- Java: `{@link #method(Type) label}`
+- JavaScript: `{@link pathOrURL|label}` or `[label]{@link pathOrURL}`
+
+#### {​@linkplain}
+- Functions identically to `{@link}`
+- Displays labels in plain text formatting rather than code font
+
+#### {​@literal text}
+- Displays text without interpreting HTML markup or nested Javadoc tags
+- Complements `{@code}` for non-code scenarios
+
+#### {​@value [package.class#constant]}
+- Shows current value of specified constant
+- Optional parameter reference
+
+---
+
+## JAVASCRIPT-SPECIFIC TAGS
+
+### Additional JavaScript Tags
+
+#### @class (synonym: @constructor)
+**Purpose**: Designates a function as a constructor requiring the `new` keyword
+
+**Usage**: Allows describing the class itself rather than just the constructor function
+
+**Example**:
+```javascript
+/**
+ * Creates a new Person.
+ * @class Represents a person.
+ */
+function Person(name) {
+    this.name = name;
+}
+```
+
+#### @file (synonyms: @fileoverview, @overview)
+**Purpose**: Documents entire file's purpose
+
+**Placement**: At beginning of file in documentation comment
+
+**Example**:
+```javascript
+/**
+ * @file
+ * This file contains utility functions for data manipulation
+ * including sorting, filtering, and transformation operations.
+ */
+```
+
+#### @property (synonym: @prop)
+**Purpose**: Streamlines documentation of static properties within classes, namespaces, or objects
+
+**Features**: Supports nested property structures with type specifications
+
+**Example**:
+```javascript
+/**
+ * @property {Number} width - The object width
+ * @property {Number} height - The object height
+ * @property {Object} config - Configuration object
+ * @property {String} config.name - Configuration name
+ */
+var defaults = {
+    width: 100,
+    height: 100,
+    config: {
+        name: 'default'
+    }
+};
+```
+
+#### @example Tag (JavaScript-Specific)
+**Purpose**: Inserts code examples into documentation comment blocks
+
+**Key Guidelines**:
+- Add empty lines and indent code lines for readability
+- Titles are optional but enhance clarity
+- Tag may be repeated multiple times in single comment
+
+**Syntax**:
+```javascript
+@example [optional title]
+[code content]
+```
+
+**Implementation Pattern - With Title**:
+```javascript
+/**
+ * Searches for matching records
+ *
+ * @example Using simple search
+ * var results = find("John");
+ *
+ * @example Using advanced filters
+ * var results = find("John", {exact: true, sortBy: "name"});
+ */
+```
+
+**Best Practices**:
+1. Use whitespace strategically for readability
+2. Include inline comments explaining code
+3. Show realistic, practical use cases
+4. Format multi-line objects with consistent indentation
+
+#### @namespace Tag
+**Purpose**: Indicates JavaScript object serves as container for organizing classes, properties, and methods
+
+**Syntax 1** (Documentation immediately precedes namespace):
+```javascript
+/**
+ * @namespace description
+ */
+var S = { ... };
+```
+
+**Syntax 2** (Indirect namespace definitions with optional type and name):
+```javascript
+/**
+ * Description
+ * @namespace [{type}] [name]
+ */
+```
+
+**Implementation Guidelines**:
+- Use Syntax 1 when comment block followed by code that defines namespace directly
+- Use Syntax 2 for indirect namespace creation
+- Ensure documented name matches actual implementation
+- Optional type and name parameters available
+
+**Practical Examples**:
+```javascript
+/**
+ * @namespace Defines namespace for UI library
+ */
+var ui = { ... };
+
+/**
+ * Defines namespace for UI library
+ * @namespace sap.ui
+ */
+jQuery.sap.define('sap.ui');
+```
+
+---
+
+## .NET DOCUMENTATION TAGS
+
+### Tag Organization for .NET
+
+**Recommended Tag Order** (Standard Sequence):
+```
+
+
+
+
+
+
+
+
+```
+
+### Comprehensive .NET Tag Reference
+
+####  Tag
+**Purpose**: Creates concise descriptions for namespaces, classes, interfaces, and their members
+
+**Syntax**:
+```xml
+short-description
+```
+
+**Key Guidelines**:
+- **Brevity and Accuracy**: "Write one summary statement containing a short and exact description"
+- Begin with capital letter
+- Conclude with period
+- Mandatory for all documented elements
+
+**Practical Example**:
+```csharp
+/// 
+/// Searches for a row that exactly matches a value or
+/// partial set of values at the current index.
+/// 
+public bool Find(short numColumns)
+```
+
+####  Tag (.NET)
+**Purpose**: Documents method and function parameters
+
+**Syntax**:
+```xml
+parameter-description
+```
+
+**Key Guidelines**:
+- **Mandatory Usage**: "Mandatory in method and function descriptions for each parameter, even if obvious"
+- Document in same sequence as method signature
+- Include necessary information about each parameter (defaults, acceptable options)
+- "Capitalize the first word in the parameter description"
+- Each parameter warrants its own dedicated tag
+
+**Practical Example**:
+```csharp
+/// The search input text
+/// Boolean flag indicating precision of search (defaults to true)
+/// The attribute used for ordering results
+public SearchResult Search(String term, Boolean exact, String sortBy)
+```
+
+####  Tag (.NET)
+**Purpose**: Documents return values for methods or functions
+
+**Syntax**:
+```xml
+returned-value-description
+```
+
+**Key Guidelines**:
+- **Mandatory**: Required for methods/functions that return values other than void
+- "Provide the necessary information about the returned value"
+- "Capitalize the first word in the returned value description"
+- Clarify all possible return scenarios
+
+**Practical Example**:
+```csharp
+/// True when the property was successfully set;
+/// otherwise, returns false.
+public Boolean SetProperty(String name, String value)
+```
+
+####  Tag
+**Purpose**: Provides detailed descriptions for namespaces, classes, interfaces, and their members
+
+**Syntax**:
+```xml
+member-description
+```
+
+**Key Guidelines**:
+- **Placement**: Insert after `` tag
+- **Content Strategy**: "Use only to provide detailed information not already mentioned in summary"
+- Expand on summary content with supplementary context
+
+**Practical Application**:
+```csharp
+/// 
+/// Searches for a specific row.
+/// 
+/// 
+/// Your client application must have an active connection to a database server
+/// before it can call this method. An exception is thrown if the connection fails.
+/// 
+public bool Find(short numColumns)
+```
+
+####  Tag (.NET)
+**Purpose**: Describes exceptions thrown during method execution
+
+**Syntax**:
+```xml
+
+    exception-description
+
+```
+
+**Key Guidelines**:
+- **Required**: For each method that throws an exception
+- List multiple exceptions in alphabetical order by name
+- "Capitalize first word in descriptions"
+- `cref` attribute specifies exception type
+- Tag body contains descriptive text
+
+**Practical Example**:
+```csharp
+/// 
+/// Thrown when the given string is not in the correct format.
+/// 
+public void Parse(String input)
+```
+
+####  Tag (.NET)
+**Purpose**: Optional XML element that adds reference link and creates See Also section
+
+**Syntax**:
+```xml
+
+```
+
+**Key Guidelines**:
+- **Parameter Lists**: Only include parameters when dealing with overloaded members
+- **Parameter Ordering**: Begin with first parameter, continue through complete list
+- **Multiple References**: Arrange progressing from simpler to more detailed
+- Start with constants, move toward namespace specifications
+
+**Practical Example**:
+```csharp
+/// 
+/// 
+public interface DownloadData {
+```
+
+####  Tag (.NET)
+**Purpose**: Optional block element adding example sections demonstrating API usage
+
+**Syntax**:
+```xml
+
+    [description]
+    
+        [sample code]
+    
+    [optional results description]
+
+```
+
+**Key Guidelines**:
+- **Optional**: For all members, but recommended
+- **Placement**: After `` tags, or after `` if no remarks
+- Include descriptive text introducing example
+- Wrap code samples in `` tags
+- Optionally describe output or behavior following code
+
+**Practical Example**:
+```csharp
+/// 
+/// The following code sample demonstrates how to open a connection:
+/// 
+/// SQLAConnection connection = new SQLAConnection();
+/// connection.Open("server=localhost");
+/// 
+/// This establishes a connection to the local database server.
+/// 
+```
+
+####  Tag
+**Purpose**: Allows placing documentation comments in XML files instead of source code
+
+**Syntax**:
+```xml
+
+```
+
+**Key Guidelines**:
+- Employ when documentation maintained separately from source code
+- Keep class/interface member documentation consolidated in single XML file
+- Use `class` to reference classes
+- Use `ctor` for constructors
+- For overloaded constructors, append numbers starting with 2 (`ctor`, `ctor2`, `ctor3`)
+
+**Benefits**:
+- Cleaner source code
+- Centralized documentation repository
+- Preserves full API documentation accessibility
+- Maintains IDE integration
+
+**Practical Implementation**:
+```csharp
+/// 
+public class MyClass {
+    public void MyMethod() { }
+}
+```
+
+---
+
+## C/C++ DOCUMENTATION TAGS
+
+### Key Difference from Java
+**Primary Distinction**: C and C++ documentation tags use **backslash prefix** (`\`) rather than `@` symbol
+
+Examples: `\param`, `\return`, `\see`
+
+### Standard Application
+- "The recommended standards and guidelines for Java apply to C and C++ as well"
+- Developers should follow similar documentation conventions
+
+### Doxygen Compatibility
+- Tags focus on compatibility with Doxygen generator
+- Popular documentation tool for C and C++ projects
+
+### C/C++ Specialized Tags
+
+#### \file Tag
+**Purpose**: Documents header files with mandatory summary and optional detailed information
+
+**Syntax**:
+```
+\file file-name
+```
+
+**Key Guidelines**:
+- **Placement**: Standalone documentation comment anywhere within header file
+- `file-name` parameter is optional
+- May include partial path for non-unique filenames
+
+**Practical Example**:
+```cpp
+/** \file sacapi.h
+ * Main API header file.
+ * This file describes all the data types and entry points of the API.
+ */
+```
+
+**Best Practices**:
+- Keep summary sentence brief and precise
+- Use optional detailed descriptions for context beyond summary
+- Include filename parameter for clarity (though optional)
+- Position documentation comment strategically for visibility
+
+#### \mainpage Tag
+**Purpose**: Generates documentation for main entry point of generated output
+
+**Syntax**:
+```
+\mainpage [title]
+```
+
+**Key Characteristics**:
+- **Placement**: Standalone documentation comment
+- Can be in any existing header file or dedicated documentation file
+- Title parameter is optional
+- Use `notitle` to suppress title display entirely
+
+**Implementation Example**:
+```cpp
+/** \mainpage ConnectionServer Component C++ API Reference
+ *
+ * This is the detailed description of the component.
+ *
+ * Main features include:
+ * - Connection management
+ * - Data transfer
+ * - Error handling
+ */
+
+namespace ConnectionServer
+{
+...
+}
+```
+
+**Key Takeaway**: Creates documentation comment to `index.html` page or first LATEX chapter of generated output
+
+---
+
+## HTML TAGS FOR DOCUMENTATION
+
+### Comprehensive HTML Tags Reference (26 Tags)
+
+#### Text Formatting Tags
+- **Bold**: `` or ``
+  - Renders text in bold font weight
+
+- **Italic**: ``, ``, or ``
+  - Renders text in italic/slanted style
+
+- **Monospaced**: ``, `
`, ``, ``, or ``
+  - Renders text in monospaced font (code font)
+  - `
`: Preserves whitespace and line breaks
+  - ``: Inline code elements
+  - ``: Keyboard input
+
+- **Small Text**: ``
+  - Renders text at smaller size
+
+- **Subscript/Superscript**: ``, ``
+  - ``: Renders below baseline
+  - ``: Renders above baseline
+
+#### Structural Elements
+- **Paragraphs**: `
`
+  - Separates content into logical blocks
+
+- **Headers**: `
` through `
`
+  - Creates hierarchical heading structure (h1 largest, h6 smallest)
+
+- **Line Breaks**: `
`
+  - Forces line break without creating new paragraph
+
+- **Horizontal Rules**: `
`
+  - Creates horizontal dividing line
+
+- **Block Quotes**: `
`
+  - Indents quoted text for emphasis
+
+#### List Tags
+- **Unordered Lists**: `
    ` with `
  • `
+  - Creates bulleted list items
+
+- **Ordered Lists**: `
      ` with `
    1. `
+  - Creates numbered list items
+
+- **Definition Lists**: `
      `, `
      `, `
      `
+  - `
      `: Defines list container
+  - `
      `: Defines term/label
+  - `
      `: Defines definition/description
+
+#### Table & Layout Tags
+- **Table Structure**: ``, ``, `
      `, ``, `
      `
+  - ``: Container for table
+  - ``: Table row
+  - `
      `: Table data cell
+  - ``: Table header cell
+  - `
      `: Table title/caption
+
+- **Centering**: `
      `
+  - Centers content horizontally
+
+#### Link Tags
+- **Hyperlinks**: `link`
+  - Creates clickable hyperlink to URL or anchor
+
+### HTML Tag Usage Guidelines
+- "Unless otherwise noted, tags terminate with a back slash: ``"
+- Use `` extensively for keywords, API names, and code samples
+- Employ `
      ` tags to maintain formatting in detailed descriptions
+- Leverage `
      ` tags within paragraph tags for code snippets
+- Use semantic HTML tags for better structure and accessibility
+
+### Common Documentation Usage Patterns
+
+**Monospaced Code References**:
+```
+The ConnectionString property specifies the database connection.
+```
+
+**Code Examples**:
+```
+
      Example usage:
      
+
      +  SQLConnection conn = new SQLConnection();
+  conn.Open("server=localhost");
+
      
+```
+
+**Structured Lists**:
+```
+
      Supported options:
      
+
        
+  
      • Option 1: Fast processing
        • 
+  
      • Option 2: Detailed logging
        • 
+  
      • Option 3: Custom configuration
        • 
+
      
+```
+
+**Nested Headers**:
+```
+
      Configuration Steps
      
+
      Follow these steps to configure:
      
+```
+
+---
+
+## BEST PRACTICES & GUIDELINES
+
+### Documentation Quality Standards
+
+#### General Principles
+1. **Always Add Value**: "Always add value to your comment"
+   - Avoid redundant documentation
+   - Don't duplicate automatically-generated information
+
+2. **Consistency**: Maintain consistency in tag ordering across all documentation
+   - Use recommended tag sequence
+   - Group multiple tags of same type together
+
+3. **Case Sensitivity**: Tags are case-sensitive
+   - Block tag comments begin with uppercase letters
+   - Follow naming conventions strictly
+
+4. **Completeness**: Document all elements
+   - Even "obvious" parameters must be documented
+   - Include every possible exception
+
+### Description Writing Guidelines
+
+#### Summary Sentence Best Practices
+- Avoid phrases like "This class" or "This method"
+- Keep lines under 80 characters to prevent wrapping
+- Write as standalone statement (appears in generated summaries)
+- Be concise but complete
+
+#### Action-Based Members
+Start with third-person verbs such as:
+- "adds," "retrieves," "provides," "returns"
+- Example: "Retrieves a Role object"
+
+#### Object-Based Members
+Use noun phrases instead of verbs:
+- Example: "Alias of a backend system"
+
+#### Detailed Descriptions
+- Add context without repeating API name or summary
+- Omit implementation details unless critical for usage
+- Use HTML tags to maintain formatting (`
      `, ``)
+- Employ `` tag for keywords, API names, code samples
+
+### Tag-Specific Best Practices
+
+#### @param Documentation
+- Document in signature order
+- Format as noun phrase describing value represented
+- Mark optional parameters clearly (JavaScript: square brackets)
+- Describe defaults and constraints
+
+#### @return/@returns Documentation
+- Wrap result names in `` tags (Java)
+- Document null or Boolean return scenarios explicitly
+- Begin with noun phrase, capital letter, no period
+
+#### @throws Documentation
+- List exceptions in alphabetical order when multiple exist
+- Complete noun phrase as standard sentence
+- Capitalize first word, no hyphen at start
+- Never use empty `@throws` tags
+
+#### @see Documentation
+- Use sparingly to maintain readability
+- Apply where it adds value
+- Use only for first occurrence of each API name
+- Java: limit frequency for easy reading
+- JavaScript: combine with `@link` for free text hyperlinks
+
+#### @deprecated Documentation
+- Never leave blank
+- Always include version and replacement reference
+- Use `{@link}` to point to successor
+- Avoid exact decommissioning timelines
+
+#### @since Documentation
+- Include specific version number
+- Support semantic versioning format
+- Apply to methods, classes, interfaces
+
+### Language-Specific Best Practices
+
+#### Java-Specific
+- Use `{@code}` for inline code snippets
+- Use `
      ` tags within `
      ` for code examples
+- Use `{@link}` for cross-references sparingly
+- Java: format parameters as noun phrases with `` wrapping
+
+#### JavaScript-Specific
+- Mark optional parameters with square brackets: `[param-name]`
+- Document union types with pipe separator: `{type1|type2}`
+- Use `{*}` for arbitrary types
+- Include type declarations with descriptions
+
+#### .NET-Specific
+- Mandatory `
      ` tag for all documented elements
+- Always use `` for every parameter
+- Always use `` for every thrown exception
+- Use `` only for supplementary information
+- Follow XML tag syntax strictly: `content`
+
+### Common Pitfalls to Avoid
+
+**❌ DO NOT**:
+- Leave tags empty or blank
+- Duplicate auto-generated information
+- Use second-person descriptions ("You should...")
+- End single-sentence tag comments with periods
+- Document parameters out of signature order
+- Miss documenting any exception
+- Use vague descriptions
+- Include implementation details
+- Skip parameters "because they're obvious"
+- Provide exact decommissioning dates for deprecated items
+
+**✅ DO**:
+- Always add value
+- Maintain consistent tag ordering
+- Use third-person descriptions
+- Document every parameter and exception
+- Capitalize first words properly
+- Use code formatting for API names
+- Include background information
+- Note special considerations
+- Cross-reference related items
+- Update version information regularly
+
+---
+
+## LANGUAGE-SPECIFIC SYNTAX
+
+### Java Documentation Comments Syntax
+
+#### Basic Structure
+```java
+/**
+ * [Summary sentence]
+ *
+ * [Detailed description - optional]
+ *
+ * @param parameter-name parameter-description
+ * @return description
+ * @throws ExceptionType description
+ * @see related-element
+ * @since version
+ * @deprecated As of version, replaced by {@link NewElement}
+ */
+```
+
+#### Example - Complete Method Documentation
+```java
+/**
+ * Retrieves the user profile for the specified user ID.
+ *
+ * 
      This method queries the user database to retrieve the complete
+ * profile information. The profile includes personal details, preferences,
+ * and security settings.
      
+ *
+ * 
      Special Considerations:
      
+ * 
        
+ *   
      • The user must be authenticated before calling this method
        • 
+ *   
      • Large profiles may take several seconds to retrieve
        • 
+ *   
      • Cache is refreshed every 5 minutes
        • 
+ * 
      
+ *
+ * @param userId An int representing the unique user identifier
+ * @param includePreferences A boolean indicating whether to include
+ *                           user preferences (defaults to true)
+ * @return A UserProfile object containing complete user information,
+ *         or null if the user does not exist
+ * @throws DatabaseException If a database error occurs while retrieving the profile
+ * @throws SecurityException If the current user lacks permission to access this profile
+ * @see UserProfile
+ * @see #updateUserProfile(int, UserProfile)
+ * @since 2.0.0
+ */
+public UserProfile getUserProfile(int userId, boolean includePreferences)
+    throws DatabaseException, SecurityException
+```
+
+### JavaScript Documentation Comments Syntax
+
+#### Basic Structure
+```javascript
+/**
+ * [Summary sentence]
+ *
+ * [Detailed description - optional]
+ *
+ * @param {type} parameter-name parameter-description
+ * @param {type} [optional-name] description
+ * @return {type} description
+ * @throws {type} description
+ * @see related-element
+ * @since version
+ * @example [optional title]
+ * [code example]
+ */
+```
+
+#### Example - Complete Function Documentation
+```javascript
+/**
+ * Searches for matching records in the database.
+ *
+ * This function provides flexible searching with support for exact matching,
+ * partial matching, and custom sorting. The search is case-insensitive by default.
+ *
+ * @param {String} query The search query string
+ * @param {Object} options Search options object
+ * @param {Boolean} [options.exact] Whether to require exact match (defaults to false)
+ * @param {String} [options.sortBy] Field name for sorting results
+ * @param {Number} [options.limit] Maximum number of results to return
+ * @return {Array.} Array of matching record objects
+ * @throws {Error} If the database connection is not established
+ * @throws {Error} If the query string is empty or invalid
+ * @example Basic search
+ * var results = search("John");
+ * @example Advanced search with options
+ * var results = search("john", {
+ *   exact: true,
+ *   sortBy: "name",
+ *   limit: 50
+ * });
+ * @see {@link DatabaseConnection}
+ * @since 1.5.0
+ */
+function search(query, options) {
+```
+
+### .NET Documentation Comments Syntax
+
+#### Basic Structure
+```csharp
+/// 
+/// [Brief description]
+/// 
+/// parameter-description
+/// return-value-description
+/// exception-description
+/// 
+/// [Additional detailed information]
+/// 
+/// 
+/// 
+/// [Code example]
+/// 
+```
+
+#### Example - Complete Method Documentation
+```csharp
+/// 
+/// Searches for a user by email address.
+/// 
+/// The email address of the user to find. Must be a valid email format.
+/// Boolean flag indicating whether to include inactive user accounts. Defaults to false.
+/// 
+/// A  object containing the user information,
+/// or null if no user with the specified email is found.
+/// 
+/// 
+/// Thrown when emailAddress is null.
+/// 
+/// 
+/// Thrown when emailAddress is not in valid email format.
+/// 
+/// 
+/// Thrown when a database error occurs during the search.
+/// 
+/// 
+/// This method performs a case-insensitive search in the user database.
+/// The search operation is performed asynchronously and may take several seconds
+/// for large user databases. Results are cached for 5 minutes to improve performance.
+/// 
+/// 
+/// The following code demonstrates how to search for a user:
+/// 
+/// User user = FindUserByEmail("john.doe@example.com", false);
+/// if (user != null)
+/// {
+///     Console.WriteLine("Found user: {0}", user.Name);
+/// }
+/// 
+/// 
+/// 
+/// 
+public User FindUserByEmail(string emailAddress, bool includeInactive)
+{
+```
+
+### C/C++ Documentation Comments Syntax (Doxygen)
+
+#### Basic Structure
+```cpp
+/**
+ * \brief [Brief description]
+ *
+ * [Detailed description]
+ *
+ * \param parameter-name parameter-description
+ * \return return-description
+ * \throws ExceptionType exception-description
+ * \see related-element
+ * \since version
+ */
+```
+
+#### Example - Complete Function Documentation
+```cpp
+/**
+ * \file database.h
+ * Database connection and query management interface.
+ * This file defines the core API for database operations including
+ * connection management, query execution, and result handling.
+ */
+
+/**
+ * \brief Retrieves a user profile by user ID.
+ *
+ * This function queries the user database to retrieve complete profile
+ * information including personal details and security settings.
+ *
+ * \param user_id The unique user identifier (must be positive)
+ * \param include_preferences Boolean flag to include user preferences
+ * \return Pointer to UserProfile structure containing user data,
+ *         or NULL if user not found
+ * \throws DatabaseError If database connection fails
+ * \throws AuthenticationError If insufficient permissions
+ * \see UserProfile
+ * \see update_user_profile
+ * \since 2.0.0
+ */
+UserProfile* get_user_profile(int user_id, bool include_preferences);
+```
+
+---
+
+## CONSOLIDATED TAG REFERENCE TABLE
+
+### All Supported Tags by Language
+
+| Tag | Java | JavaScript | .NET | C/C++ | Purpose |
+|-----|------|-----------|------|-------|---------|
+| @param /  | ✓ | ✓ | ✓ | \param | Document parameters |
+| @return /  | ✓ | ✓ | ✓ | \return | Document return values |
+| @throws /  | ✓ | ✓ | ✓ | N/A | Document exceptions |
+| @see /  | ✓ | ✓ | ✓ | \see | Create cross-references |
+| @deprecated | ✓ | ✓ | N/A | N/A | Mark deprecated elements |
+| @since / \since | ✓ | ✓ | N/A | \since | Indicate version introduction |
+| @version | ✓ | ✓ | N/A | N/A | Internal version tracking |
+|  | N/A | N/A | ✓ | N/A | Brief description (.NET) |
+|  | N/A | N/A | ✓ | N/A | Detailed description (.NET) |
+|  | ✓ | ✓ | ✓ | N/A | Code examples |
+| @class / @constructor | N/A | ✓ | N/A | N/A | Constructor documentation |
+| @file / \file | N/A | ✓ | N/A | ✓ | File documentation |
+| @property | N/A | ✓ | N/A | N/A | Property documentation |
+| @namespace | N/A | ✓ | N/A | N/A | Namespace documentation |
+|  | N/A | N/A | ✓ | N/A | External documentation reference |
+| \mainpage | N/A | N/A | N/A | ✓ | Main page documentation |
+| Inline tags | {@code}, {@link}, {@docRoot}, {@inheritDoc}, {@linkplain}, {@literal}, {@value} | Standard | N/A | N/A | Inline formatting |
+
+---
+
+## CUSTOM & LEGACY TAGS
+
+### Legacy Java Tags (Backward Compatibility)
+
+| Tag | Purpose | Status |
+|-----|---------|--------|
+| @author | Indicates API author name/ID | Legacy - internal only |
+| @brief | Concise description | Legacy - not recommended |
+| @details | Comprehensive explanations | Legacy - not recommended |
+| @examples | Mark example sections | Legacy - use  instead |
+| @noextend | Prevent class/interface extension | Legacy - not recommended |
+| @noimplement | Prevent interface implementation | Legacy - not recommended |
+| @noinstantiate | Block class instantiation | Legacy - not recommended |
+| @nooverride | Restrict method extension | Legacy - not recommended |
+| @noreference | Restrict public member access | Legacy - not recommended |
+| @hideinitializers | Conceal enum value docs | Legacy - not recommended |
+| @showinitializers | Display enum value docs | Legacy - not recommended |
+| @overloadedbrief | Summarize overloaded methods | Legacy - not recommended |
+| @titlesuffix | Append text to section titles | Legacy - not recommended |
+
+---
+
+## KEY TAKEAWAYS & IMPLEMENTATION SUMMARY
+
+### Critical Documentation Principles
+
+1. **Source-Driven Documentation**: Documentation lives in source code, not separate files
+   - Enables automatic generation
+   - Reduces maintenance burden
+   - Ensures documentation stays current
+
+2. **Standardized Structure**: Three-tier approach
+   - **Metadata Layer**: YAML frontmatter with name/description
+   - **Content Layer**: Detailed descriptions and examples
+   - **Metadata Tags**: Structured information for generation tools
+
+3. **Language Consistency**: Core principles apply across Java, JavaScript, and .NET
+   - Verb-based method documentation
+   - Consistent tag ordering
+   - Consistent parameter documentation patterns
+
+4. **Quality Over Quantity**: Add value with every documentation element
+   - Avoid redundancy
+   - Complete information coverage
+   - Clear, professional writing
+
+5. **User-Centered Documentation**: Think about developer experience
+   - First-occurrence explanation completeness
+   - Clear cross-references
+   - Practical examples
+   - Special considerations highlighted
+
+### Implementation Checklist
+
+Before finalizing documentation:
+
+- [ ] Description is mandatory and comprehensive
+- [ ] Tags ordered: @param → @return → @throws → @see → @since → @deprecated
+- [ ] Every parameter has @param tag
+- [ ] Non-void methods have @return tag
+- [ ] Every exception has @throws tag
+- [ ] Related items linked with @see tags
+- [ ] Code elements wrapped in `` tags
+- [ ] Examples use `
      ` tags with proper indentation
+- [ ] Complex concepts explained without assuming prior knowledge
+- [ ] No redundancy with auto-generated information
+- [ ] Proper capitalization and punctuation
+- [ ] Version information current and accurate
+
+---
+
+## REFERENCES & OFFICIAL STANDARDS
+
+**Official SAP API Style Guide**: [https://github.com/SAP-docs/api-style-guide/tree/main/docs/40-java-javascript-and-msnet](https://github.com/SAP-docs/api-style-guide/tree/main/docs/40-java-javascript-and-msnet)
+
+**All 39 Files Extracted & Consolidated**: 2025-11-21
+
+**Compliance**: Follows official Anthropic skills specification and SAP standards
+
+---
+
+**End of Complete Reference Documentation**
diff --git a/references/manual-templates-guide.md b/references/manual-templates-guide.md
new file mode 100644
index 0000000..1517d6d
--- /dev/null
+++ b/references/manual-templates-guide.md
@@ -0,0 +1,2765 @@
+# Manual REST and OData API Documentation Templates Guide
+
+**Source**: [https://github.com/SAP-docs/api-style-guide/tree/main/docs/50-manually-written-rest-and-odata](https://github.com/SAP-docs/api-style-guide/tree/main/docs/50-manually-written-rest-and-odata)
+
+**Last Verified**: 2025-11-21
+
+**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))
+
+**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates.
+
+**Purpose**: Comprehensive reference for manually documenting REST and OData APIs with standardized templates and best practices
+
+---
+
+## TABLE OF CONTENTS
+
+1. [Overview of Manual Documentation](#overview-of-manual-documentation)
+2. [When to Use Manual Templates](#when-to-use-manual-templates)
+3. [REST API Templates](#rest-api-templates)
+4. [OData API Templates](#odata-api-templates)
+5. [Template Comparison Table](#template-comparison-table)
+6. [Best Practices](#best-practices)
+7. [Complete Working Examples](#complete-working-examples)
+8. [Field-by-Field Requirements](#field-by-field-requirements)
+9. [Hierarchical Linking Guidance](#hierarchical-linking-guidance)
+
+---
+
+## OVERVIEW OF MANUAL DOCUMENTATION
+
+### What Is Manual API Documentation?
+
+Manual API documentation is custom-written reference content created when:
+- Auto-generated documentation doesn't meet product requirements
+- API documentation needs to be integrated into developer guides
+- Custom documentation structure and presentation is required
+- Documentation control and customization is a priority
+
+### Auto-Generated vs Manual Documentation
+
+| Aspect | Auto-Generated | Manual |
+|--------|---|---|
+| **Source** | OpenAPI specs, code annotations | Written documentation files |
+| **Customization** | Limited to spec structure | Full control over structure and content |
+| **Maintenance** | Updates with code changes | Manual synchronization needed |
+| **Location** | Separate documentation portal | Integrated into guides |
+| **Use Case** | Standard API catalogs | Custom developer guides |
+| **Completeness** | Technical accuracy guaranteed | Requires careful review |
+
+### Key Principle: Two-Tier Organization
+
+Both REST and OData manual documentation follow a hierarchical approach:
+1. **Level 1**: Overview (service/resource grouping)
+2. **Level 2+**: Detailed documentation (methods/resources/operations)
+
+This prevents redundancy and improves navigation.
+
+---
+
+## WHEN TO USE MANUAL TEMPLATES
+
+Use manual documentation templates when:
+
+1. **Documentation Doesn't Match Product Needs**
+   - Auto-generated structure doesn't align with your service
+   - Need custom grouping and organization
+
+2. **Integration into Developer Guides**
+   - API documentation must be embedded in larger guides
+   - Single-document strategy preferred over separate catalogs
+
+3. **Custom Presentation Requirements**
+   - Need specific formatting or layout
+   - Want to control example placement and detail level
+
+4. **Complex Multi-Part Services**
+   - Large services with many related resources
+   - Clear hierarchy needed for navigation
+
+5. **Regulatory or Compliance Requirements**
+   - Documentation control is mandatory
+   - Version tracking within guides is essential
+
+---
+
+## REST API TEMPLATES
+
+### Overview: REST Two-Level Structure
+
+REST API documentation uses a 2-level hierarchy:
+- **Level 1: REST API Overview** - Documents related REST methods for same resource
+- **Level 2: REST API Method** - Documents individual REST methods/endpoints
+
+### REST API Overview Template (Level 1)
+
+The Overview Template documents a set of related REST methods that apply to the same resource or service.
+
+#### Template Sections
+
+##### 1. Title and Introduction
+
+**Format**: Descriptive title of the REST API or resource
+**Description**: Short description of the REST API or set of REST methods that apply to the same resource
+
+**Example Title**:
+```
+Employees REST API
+```
+
+**Example Description**:
+```
+Provides methods to retrieve, create, update, and delete employee records.
+Supports querying employees by department, status, and other criteria.
+```
+
+##### 2. Base Information
+
+**Base URI**
+- Absolute endpoint where API is hosted
+- Example: `[https://api.example.com/v1/employees`](https://api.example.com/v1/employees`)
+- Include protocol, host, and path prefix
+
+**Permissions**
+- Required roles/permissions to access API
+- List by operation type (read, write, delete)
+- Example: "Requires HR_MANAGER or ADMIN role"
+
+**Additional Context**
+- Notes about API usage and scope
+- Any prerequisites for calling the API
+
+**Template Structure**:
+```
+## Base Information
+
+Base URI: [Absolute URI, e.g., [https://api.example.com/v1]](https://api.example.com/v1])
+
+Permissions: [Required permissions, e.g., ROLE_USER, ROLE_ADMIN]
+
+Additional Notes: [Any important context about the API]
+```
+
+##### 3. Methods Section
+
+**Purpose**: Catalog all available HTTP methods for the resource
+
+**Table Structure**:
+| HTTP Method | Action | URI |
+|---|---|---|
+| [GET/POST/PUT/DELETE/PATCH] | [Link to detailed method doc] | [Relative URI] |
+
+**Detailed Example**:
+| HTTP Method | Action | URI |
+|---|---|---|
+| GET | [List All Employees](#list-all-employees) | `/employees` |
+| GET | [Get Employee by ID](#get-employee-by-id) | `/employees/{employeeId}` |
+| POST | [Create Employee](#create-employee) | `/employees` |
+| PUT | [Update Employee](#update-employee) | `/employees/{employeeId}` |
+| DELETE | [Delete Employee](#delete-employee) | `/employees/{employeeId}` |
+
+**Best Practices**:
+- Actions should be links to detailed method documentation
+- URIs are relative to Base URI
+- Order by operation type (GET, POST, PUT, DELETE, PATCH)
+- Use consistent URI naming conventions
+
+##### 4. Common Request Headers Documentation
+
+**Purpose**: Document HTTP headers used in requests to the API
+
+**Table Structure**:
+| Header Name | Required | Description |
+|---|---|---|
+| [Header name] | [Yes/No] | [Description with possible/default values] |
+
+**Common Headers Example**:
+| Header Name | Required | Description |
+|---|---|---|
+| Authorization | Yes | Bearer token for authentication. Format: `Authorization: Bearer {token}` |
+| Content-Type | Yes | Media type of request body. Value: `application/json` |
+| Accept | No | Preferred response format. Default: `application/json` |
+| X-Request-ID | No | Optional request ID for tracking. Any UUID format accepted |
+
+**Field Descriptions**:
+- **Header Name**: Exact header name as expected (case-sensitive)
+- **Required**: Yes if header must be present, No if optional
+- **Description**: Explain purpose, format, constraints, and default values if applicable
+
+##### 5. Common Response Headers Documentation
+
+**Purpose**: Document HTTP headers that appear in responses
+
+**Table Structure**:
+| Header Name | Description |
+|---|---|
+| [Header name] | [Purpose and possible values] |
+
+**Common Response Headers Example**:
+| Header Name | Description |
+|---|---|
+| Content-Type | Type of response body. Value: `application/json` |
+| X-Total-Count | Total number of resources available (for paginated responses) |
+| X-RateLimit-Remaining | Number of API calls remaining in current rate limit window |
+| Location | URL of newly created resource (returned by POST operations creating resources) |
+
+##### 6. Status Codes Section
+
+**Purpose**: Catalog all possible HTTP status codes returned by the API
+
+**Table Structure**:
+| Status Code | Result Description |
+|---|---|
+| [2xx/3xx/4xx/5xx] | [What this status means in context of your API] |
+
+**Common Status Codes Example**:
+
+Success Codes:
+| Status Code | Result Description |
+|---|---|
+| 200 OK | Request successful. Response body contains requested data |
+| 201 Created | Resource successfully created. Location header contains URL to new resource |
+| 204 No Content | Request successful. No response body returned (typically for DELETE) |
+
+Error Codes:
+| Status Code | Result Description |
+|---|---|
+| 400 Bad Request | Invalid request format or missing required fields |
+| 401 Unauthorized | Authentication required or token invalid/expired |
+| 403 Forbidden | Authenticated but insufficient permissions for resource |
+| 404 Not Found | Requested resource doesn't exist |
+| 409 Conflict | Request conflicts with current state (e.g., duplicate creation) |
+| 500 Internal Server Error | Server encountered unexpected error |
+
+#### Complete REST Overview Template Example
+
+```markdown
+# Employees REST API
+
+Provides methods to retrieve, create, update, and delete employee records.
+Supports querying employees by department, status, organizational hierarchy,
+and other criteria.
+
+## Base Information
+
+**Base URI**: `[https://api.example.com/v1/employees`](https://api.example.com/v1/employees`)
+
+**Permissions**: ROLE_HR_USER (read), ROLE_HR_MANAGER (write/delete)
+
+**Additional Notes**:
+- All requests require Bearer token authentication
+- API supports pagination with `limit` and `offset` parameters
+- Rate limit: 1000 requests per hour
+
+## Methods
+
+| HTTP Method | Action | URI |
+|---|---|---|
+| GET | [List all employees](#get-employees-list) | `/employees` |
+| GET | [Get employee by ID](#get-employee) | `/employees/{employeeId}` |
+| POST | [Create new employee](#post-employee) | `/employees` |
+| PUT | [Update employee](#put-employee) | `/employees/{employeeId}` |
+| PATCH | [Partially update employee](#patch-employee) | `/employees/{employeeId}` |
+| DELETE | [Delete employee](#delete-employee) | `/employees/{employeeId}` |
+
+## Common Request Headers
+
+| Header Name | Required | Description |
+|---|---|---|
+| Authorization | Yes | Bearer token for authentication. Format: `Authorization: Bearer {token}` |
+| Content-Type | Yes | Media type for request body. Value: `application/json` |
+| Accept | No | Preferred response format. Default: `application/json` |
+| X-Request-ID | No | Optional request tracking ID. Any UUID format |
+| If-Match | No | ETag for optimistic locking (for PUT/PATCH). Example: `"abc123def456"` |
+
+## Common Response Headers
+
+| Header Name | Description |
+|---|---|
+| Content-Type | Type of response body. Value: `application/json` |
+| X-Total-Count | Total number of available resources (paginated responses) |
+| X-RateLimit-Remaining | Remaining API calls in current rate limit window |
+| ETag | Entity tag for caching and optimistic locking |
+| Location | URL of newly created resource (201 Created responses) |
+| Retry-After | Seconds to wait before retrying (429 Too Many Requests) |
+
+## Status Codes
+
+**Success Codes**:
+| Status Code | Result Description |
+|---|---|
+| 200 OK | Request successful. Response contains employee data |
+| 201 Created | Employee successfully created. Location header contains new employee URL |
+| 204 No Content | Deletion successful. No response body returned |
+
+**Error Codes**:
+| Status Code | Result Description |
+|---|---|
+| 400 Bad Request | Invalid request format or missing required fields. Check error details |
+| 401 Unauthorized | Authentication token missing, invalid, or expired |
+| 403 Forbidden | Authenticated but insufficient permissions for operation |
+| 404 Not Found | Employee with specified ID doesn't exist |
+| 409 Conflict | Employee email already exists or data conflict prevents operation |
+| 500 Internal Server Error | Server error. Contact support if issue persists |
+```
+
+---
+
+### REST API Method Template (Level 2)
+
+The Method Template documents individual REST API methods/endpoints with detailed information.
+
+#### Template Sections
+
+##### 1. Title and Introduction
+
+**Format**: Action + Resource
+**Content**: Brief description of what the method does
+
+**Examples**:
+- "List All Employees"
+- "Get Employee by ID"
+- "Create New Employee"
+- "Update Employee"
+- "Delete Employee"
+
+**Description Template**:
+```
+Brief description of the REST method's purpose and primary function.
+Include what the method retrieves, creates, modifies, or deletes.
+```
+
+**Example Description**:
+```
+Retrieves a complete list of all employees in the system with support
+for filtering, sorting, and pagination.
+```
+
+##### 2. Usage Section
+
+**Purpose**: Explain when and how to use this method
+
+**Content**:
+- Additional information about the method
+- Functionality details beyond the summary
+- When to use this method vs. alternatives
+- Any important prerequisites or constraints
+
+**Template**:
+```
+## Usage
+
+Use this method when [explain scenario].
+
+Key points:
+- [Important characteristic or constraint]
+- [Related method if applicable]
+- [Performance consideration if relevant]
+```
+
+**Example**:
+```
+## Usage
+
+Use this method to retrieve all employee records with optional filtering
+and pagination.
+
+Key points:
+- Supports filtering by multiple fields using query parameters
+- Returns paginated results (default: 20 per page, max: 100)
+- Results sorted by employee ID unless otherwise specified
+- Related method: GET /employees/{employeeId} for specific employee
+```
+
+##### 3. Request Details Section
+
+**3.1 Request Line**
+```
+[HTTP METHOD] [Relative URI Path]
+
+GET /employees
+GET /employees/{employeeId}
+POST /employees
+```
+
+**3.2 HTTP Method Specification**
+- Exact HTTP method: GET, POST, PUT, PATCH, DELETE
+- Must match operation being documented
+
+**3.3 Permission Requirements**
+- Required role or permission
+- Related to operation type (read, write, delete)
+
+**Template**:
+```
+Permission: [Required role, e.g., ROLE_HR_USER for read, ROLE_HR_MANAGER for write]
+```
+
+**3.4 Common Request Headers Reference**
+- Reference headers documented in Overview
+- Note any method-specific header requirements
+
+**Template**:
+```
+Refer to [Common Request Headers](#common-request-headers) in overview.
+
+Additional method-specific headers: [List any specific headers]
+```
+
+**3.5 Parameter Documentation**
+
+**Table Structure**:
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| [Name] | Required/Optional | [Type] | [Description of purpose and constraints] | [Path/Query/Body/Header] |
+
+**Detailed Parameter Examples**:
+
+*Path Parameters* (required):
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| employeeId | Required | String | Unique employee identifier. Pattern: `E[0-9]{5}` | Path |
+
+*Query Parameters* (optional filtering/pagination):
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| limit | Optional | Integer | Maximum results per page. Range: 1-100. Default: 20 | Query |
+| offset | Optional | Integer | Number of results to skip for pagination. Default: 0 | Query |
+| department | Optional | String | Filter by department code. Example: "SALES" | Query |
+| status | Optional | String | Filter by employee status. Valid: "ACTIVE", "INACTIVE", "LEAVE" | Query |
+| sortBy | Optional | String | Sort field. Valid: "name", "hireDate", "salary" | Query |
+
+*Request Body* (for POST/PUT):
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| firstName | Required | String | Employee's first name. Length: 1-50 characters | Body |
+| lastName | Required | String | Employee's last name. Length: 1-50 characters | Body |
+| email | Required | String | Corporate email. Must be unique. Format: valid email | Body |
+| department | Required | String | Department code. Example: "SALES" | Body |
+| hireDate | Optional | String | Hire date in YYYY-MM-DD format. Example: "2024-01-15" | Body |
+| salary | Optional | Decimal | Annual salary in USD. Minimum: 20000 | Body |
+
+**Parameter Field Descriptions**:
+- **Parameter Name**: Exact name as expected in request
+- **Requirement**: Required or Optional
+- **Data Type**: string, integer, boolean, number, date, array, object
+- **Description**: Explain purpose, format requirements, valid values, constraints
+- **Location**: Path (URI), Query (URL params), Body (request payload), Header
+
+**3.6 Request Body Example**
+
+**For POST/PUT/PATCH**: Include JSON structure
+
+**Template**:
+```
+## Request Body
+
+[JSON example with actual data structures]
+
+## Request Example
+
+[Complete curl or HTTP request example]
+```
+
+**Example**:
+```
+## Request Body
+
+```json
+{
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2024-01-15",
+  "salary": 95000.00
+}
+```
+
+## Request Example
+
+```
+POST /employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Content-Type: application/json
+
+{
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2024-01-15",
+  "salary": 95000.00
+}
+```
+```
+
+##### 4. Response Information Section
+
+**4.1 HTTP Status Codes and Descriptions**
+
+**Table Structure**:
+| Status Code | Description |
+|---|---|
+| [Code] | [What this code means for this operation] |
+
+**Common Response Status Codes Example**:
+
+For GET method:
+| Status Code | Description |
+|---|---|
+| 200 OK | List successfully retrieved. Response body contains employee array |
+| 401 Unauthorized | Authentication token missing or invalid |
+| 403 Forbidden | Insufficient permissions to access employee data |
+| 500 Internal Server Error | Server error. Contact support |
+
+For POST method:
+| Status Code | Description |
+|---|---|
+| 201 Created | Employee successfully created. Location header contains new employee URL |
+| 400 Bad Request | Invalid request format. Check firstName, lastName, email, department |
+| 401 Unauthorized | Authentication token missing or invalid |
+| 409 Conflict | Employee with specified email already exists |
+| 500 Internal Server Error | Server error. Contact support |
+
+**4.2 Response Body Example**
+
+**For successful response**:
+```json
+{
+  "employeeId": "E12345",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2024-01-15",
+  "salary": 95000.00,
+  "status": "ACTIVE",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "lastModified": "2024-01-15T10:30:00Z"
+}
+```
+
+**4.3 Response Example with Headers**
+
+**Template**:
+```
+HTTP/1.1 [Status Code] [Status Message]
+Content-Type: application/json
+Location: [Relevant URLs for created resources]
+X-Total-Count: [Total count for paginated responses]
+
+[Response body JSON]
+```
+
+**Example for POST (201 Created)**:
+```
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: [https://api.example.com/v1/employees/E12346](https://api.example.com/v1/employees/E12346)
+
+{
+  "employeeId": "E12346",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2024-01-15",
+  "salary": 95000.00,
+  "status": "ACTIVE",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+#### Complete REST Method Template Example
+
+```markdown
+## Get Employee by ID
+
+Retrieves complete employee information for a specific employee including
+personal data, organizational assignments, and compensation details.
+
+### Usage
+
+Use this method to retrieve full details of a specific employee when you know
+their employee ID. Returns all employee information in a single request.
+
+Key points:
+- Returns complete employee profile
+- Requires valid employee ID in path
+- Related method: GET /employees for listing all employees
+
+### Request
+
+GET /employees/{employeeId}
+
+Permission: ROLE_HR_USER (read access)
+
+#### Path Parameters
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| employeeId | Required | String | Unique employee identifier. Pattern: `E[0-9]{5}`. Example: "E12345" | Path |
+
+#### Request Headers
+
+Refer to [Common Request Headers](#common-request-headers) in overview.
+
+### Response
+
+#### Status Codes
+
+| Status Code | Description |
+|---|---|
+| 200 OK | Employee successfully retrieved. Response body contains complete employee data |
+| 401 Unauthorized | Authentication token missing, invalid, or expired |
+| 403 Forbidden | Authenticated but insufficient permissions to access this employee |
+| 404 Not Found | No employee found with provided employeeId |
+| 500 Internal Server Error | Server error. Contact support if issue persists |
+
+#### Response Body
+
+```json
+{
+  "employeeId": "E12345",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "jobTitle": "Senior Software Engineer",
+  "manager": {
+    "employeeId": "E10001",
+    "firstName": "Jane",
+    "lastName": "Smith"
+  },
+  "hireDate": "2020-06-01",
+  "salary": 120000.00,
+  "currency": "USD",
+  "status": "ACTIVE",
+  "officeLocation": "San Francisco",
+  "createdAt": "2020-06-01T09:00:00Z",
+  "lastModified": "2024-01-15T14:30:00Z"
+}
+```
+
+#### Response Example
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+X-RateLimit-Remaining: 998
+
+{
+  "employeeId": "E12345",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2020-06-01",
+  "salary": 120000.00,
+  "status": "ACTIVE"
+}
+```
+
+#### Error Response Example (404 Not Found)
+
+```
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "No employee found with ID E99999",
+    "details": {
+      "resourceType": "Employee",
+      "providedId": "E99999"
+    }
+  }
+}
+```
+```
+
+#### REST Method Template Structure Checklist
+
+- [ ] Title (action + resource)
+- [ ] Introduction/description
+- [ ] Usage section with key points
+- [ ] Request line (HTTP METHOD + URI)
+- [ ] Permission requirements
+- [ ] Common headers reference
+- [ ] Parameter documentation table
+- [ ] Parameter location (Path/Query/Body/Header)
+- [ ] Request body example (for POST/PUT/PATCH)
+- [ ] Complete request example
+- [ ] Status codes with descriptions
+- [ ] Response body example (JSON structure)
+- [ ] Complete response example with headers
+- [ ] Error response example(s)
+
+---
+
+### REST API Templates - Usage Guidelines
+
+#### Two-Level Organization
+
+**Level 1 - Overview Template**:
+- Use for overview of related REST API methods that apply to the same resource or belong to the same service
+- Contains shared information (base URI, permissions, common headers)
+- Includes method list with links to detailed documentation
+
+**Level 2 - Method Template**:
+- Use for documenting individual REST API endpoints
+- Contains method-specific details
+- Should not repeat information from Overview
+
+#### Best Practices for REST Templates
+
+1. **Organize by Resource or Service**
+   - Group related methods under unified overview documentation
+   - Don't treat each endpoint in isolation
+   - Example: All employee methods together, all department methods together
+
+2. **Separate Common from Specific Information**
+   - Place authentication, base URLs, common parameters in Overview
+   - Reserve Method templates for endpoint-specific content
+   - Reduces redundancy and improves maintainability
+
+3. **Maintain Clear Navigation**
+   - Overview documents must include list of methods with links to detailed docs
+   - Method docs should link back to Overview
+   - Help users navigate between related endpoints
+
+4. **Consistent Structure**
+   - Follow standardized templates exactly
+   - Ensures documentation quality across API
+   - Developers become familiar with format
+
+5. **Complete Parameter Documentation**
+   - Always specify parameter location (Path/Query/Body/Header)
+   - Include constraints (min/max, patterns, valid values)
+   - Document default values
+   - Explain what each parameter controls
+
+6. **Contextual Status Code Descriptions**
+   - Don't just list codes—explain what they mean for THIS method
+   - Example: "200 OK: Employee successfully retrieved with full profile"
+   - Not just: "200 OK: Request successful"
+
+7. **Real Examples**
+   - Provide working request/response examples
+   - Use realistic data that matches parameter documentation
+   - Show common use cases and error scenarios
+
+---
+
+## OData API TEMPLATES
+
+### Overview: OData Three-Level Structure
+
+OData API documentation uses a 3-level hierarchy:
+- **Level 1: OData Service Overview** - Describes entire OData service
+- **Level 2: OData Resource** - Documents individual resources/entity sets
+- **Level 3: OData Operation** - Documents single operations on resources
+
+---
+
+### OData Service Overview Template (Level 1)
+
+The Service Overview Template documents a complete OData service with metadata and resource listing.
+
+#### Template Sections
+
+##### 1. Title and Introduction
+
+**Format**: Service Name
+**Content**: Brief description of the OData service
+
+**Example Title**:
+```
+Employees OData Service
+```
+
+**Example Description**:
+```
+Provides OData v4 API for accessing and managing employee data including
+personal information, organizational assignments, and compensation details.
+Supports full CRUD operations with complex filtering and navigation.
+```
+
+##### 2. Overview Section
+
+**2.1 OData Version**
+
+Specify which OData version(s) the service supports:
+```
+OData Version: 4.0 | 3.0 | 2.0
+```
+
+Different versions have different capabilities:
+- **OData 4.0**: Latest version with modern features
+- **OData 3.0**: Older but widely supported version
+- **OData 2.0**: Legacy version (limited features)
+
+**Example**:
+```
+OData Version: 4.0 (with 3.0 backward compatibility available via `/odata/v3` endpoint)
+```
+
+**2.2 Root URI**
+
+Absolute URI where OData service is accessible:
+```
+Root URI: [Absolute service path]
+```
+
+Include:
+- Protocol (https://)
+- Host
+- Service path
+- Example: `[https://api.example.com/odata/v4/employees`](https://api.example.com/odata/v4/employees`)
+
+**Example**:
+```
+Root URI: `[https://api.example.com/odata/v4`](https://api.example.com/odata/v4`)
+
+Service endpoints:
+- Employees: `/odata/v4/Employees`
+- Departments: `/odata/v4/Departments`
+- Compensation: `/odata/v4/Compensation`
+```
+
+**2.3 Permissions and Roles**
+
+Required permissions to access the OData service:
+```
+Required Permissions: [List roles and what they allow]
+```
+
+**Example**:
+```
+Required Permissions:
+- ROLE_HR_USER: Read access to all resources
+- ROLE_HR_MANAGER: Read and write access to employee data
+- ROLE_FINANCE: Read access to compensation data only
+```
+
+**2.4 OData Feature Support Matrix**
+
+Document which OData features the service supports:
+
+| Feature | Supported | Notes |
+|---|---|---|
+| Filtering ($filter) | Yes | All comparison operators supported |
+| Ordering ($orderby) | Yes | Ascending and descending |
+| Paging ($top, $skip) | Yes | Maximum 1000 records per request |
+| Selection ($select) | Yes | Choose specific properties |
+| Expansion ($expand) | Yes | Limited to 2 levels deep |
+| Functions | Yes | Custom business logic operations |
+| Actions | No | Not implemented in this version |
+| Batch Requests | No | Each request handled individually |
+| Metadata Filtering | Yes | Via $metadata endpoint |
+
+**Template**:
+```
+## OData Feature Support
+
+| Feature | Supported | Notes |
+|---|---|---|
+| [Feature name] | Yes/No/Partial | [Any specific details or constraints] |
+```
+
+##### 3. Entity Data Model Section
+
+**3.1 Entity Relationship Diagram**
+
+Document the data model visually or with description:
+```
+Include diagram or detailed description of entity relationships:
+- Entity types
+- Navigation properties
+- Associations
+```
+
+**Example Description**:
+```
+The service includes the following entity types:
+- Employee: Contains personal and employment information
+  - Has relationship to Department (Navigation: Department)
+  - Has relationship to Manager (Navigation: Manager)
+  - Has relationship to Compensation (Navigation: Compensation)
+
+- Department: Contains organization structure
+  - Has relationship to Employees (Navigation: Employees)
+  - Has relationship to Parent Department (Navigation: ParentDepartment)
+
+- Compensation: Contains salary and benefits
+  - Has relationship to Employee (Navigation: Employee)
+```
+
+**3.2 Service Metadata URI**
+
+Endpoint to retrieve service metadata:
+```
+Service Metadata URI: [Root URI]/$metadata
+```
+
+The $metadata endpoint provides:
+- Entity definitions and properties
+- Navigation properties and relationships
+- OData function and action definitions
+- Service capabilities
+
+**Example**:
+```
+Service Metadata URI: `[https://api.example.com/odata/v4/$metadata`](https://api.example.com/odata/v4/$metadata`)
+
+This endpoint returns the complete service definition in CSDL (Common Schema Definition Language) format.
+Useful for code generation and understanding the full service structure.
+```
+
+**3.3 Additional Model Notes**
+
+Any important information about the data model:
+- Property constraints
+- Complex types
+- Computed properties
+- Inheritance structures
+
+**Example**:
+```
+## Additional Model Notes
+
+- All timestamps are in UTC format (ISO 8601)
+- Employee IDs follow pattern: E[0-9]{5}
+- Salary values are in local currency as specified in Compensation entity
+- Department hierarchies can nest up to 10 levels deep
+```
+
+##### 4. Resources Section
+
+**Purpose**: List all entity sets available in the service
+
+**Table Structure** (can have multiple tables organized by category):
+
+| Resource Name | Description | Path |
+|---|---|---|
+| [Entity Set Name] | [Description of what resource contains] | [Relative path] |
+
+**Detailed Example**:
+
+| Resource Name | Description | Path |
+|---|---|---|
+| [Employees](#odata-resource-employees) | Collection of all employees in system | `/Employees` |
+| [Departments](#odata-resource-departments) | Organization departments and structure | `/Departments` |
+| [Compensation](#odata-resource-compensation) | Employee salary and benefits data | `/Compensation` |
+
+**Formatting Guidelines**:
+- Resource names should be links to detailed resource documentation
+- Descriptions should be concise but informative
+- Paths are relative to root URI
+- Organized alphabetically or by category
+
+#### Complete OData Service Overview Template Example
+
+```markdown
+# Employees OData Service
+
+Provides OData v4 API for accessing and managing employee data including
+personal information, organizational assignments, compensation details, and
+organizational hierarchy. Supports full CRUD operations with complex filtering
+and advanced query capabilities.
+
+## Overview
+
+**OData Version**: 4.0 (with backward compatibility for 3.0 via separate endpoints)
+
+**Root URI**: `[https://api.example.com/odata/v4`](https://api.example.com/odata/v4`)
+
+**Required Permissions**:
+- ROLE_HR_USER: Read access to all resources
+- ROLE_HR_MANAGER: Read and write access to employee and department data
+- ROLE_FINANCE: Read access to compensation data
+- ROLE_ADMIN: Full read/write access to all resources
+
+## OData Feature Support
+
+| Feature | Supported | Notes |
+|---|---|---|
+| Filtering ($filter) | Yes | All OData comparison operators, logical operators |
+| Ordering ($orderby) | Yes | Single and multiple field ordering, ascending/descending |
+| Paging ($top, $skip) | Yes | Max 1000 records per request, default 50 |
+| Selection ($select) | Yes | Choose specific properties to reduce payload |
+| Expansion ($expand) | Yes | Navigate relationships, limited to 3 levels deep |
+| Counting ($count) | Yes | Get total record count |
+| Functions | Yes | Custom business functions supported |
+| Actions | Partial | Limited action support for specific operations |
+| Batch Requests | Yes | Multiple operations in single request |
+| Media Resources | No | File upload/download not supported |
+
+## Entity Data Model
+
+The service manages the following entity relationships:
+
+**Employee Entity**:
+- Contains employee personal and employment data
+- Navigates to Department (organization assignment)
+- Navigates to Manager (reporting relationship)
+- Navigates to Compensation (salary/benefits)
+- Properties: EmployeeID, FirstName, LastName, Email, HireDate, Status, etc.
+
+**Department Entity**:
+- Contains organization structure
+- Navigates to Employees (all members)
+- Navigates to Parent Department (hierarchy)
+- Properties: DepartmentID, Name, Manager, Location, Cost Center, etc.
+
+**Compensation Entity**:
+- Contains salary and benefits information
+- Navigates to Employee
+- Properties: CompensationID, EmployeeID, BaseSalary, Currency, Benefits, etc.
+
+**Service Metadata URI**: `[https://api.example.com/odata/v4/$metadata`](https://api.example.com/odata/v4/$metadata`)
+
+The metadata endpoint returns the complete service definition. Use for understanding
+entity properties, relationships, and available operations.
+
+## Resources
+
+| Resource Name | Description | Path |
+|---|---|---|
+| [Employees](#employees-resource) | All employees in the system | `/Employees` |
+| [Departments](#departments-resource) | Organization departments and structure | `/Departments` |
+| [Compensation](#compensation-resource) | Employee compensation and benefits | `/Compensation` |
+
+## Additional Information
+
+- All timestamps use UTC format (ISO 8601)
+- Employee IDs follow pattern: E[0-9]{5} (example: E12345)
+- Salary values in specified currency (see Compensation entity)
+- Department hierarchies can nest up to 10 levels
+- Maximum request payload: 10 MB
+- Rate limit: 1000 requests per hour per user
+```
+
+---
+
+### OData Resource Template (Level 2)
+
+The Resource Template documents individual resources/entity sets within the OData service.
+
+#### Template Sections
+
+##### 1. Title and Introduction
+
+**Format**: Resource Name
+**Content**: Description of what the resource represents and contains
+
+**Example Title**:
+```
+Employees Resource
+```
+
+**Example Description**:
+```
+Collection of all employees in the system. Provides access to employee master
+data including personal information, organizational assignments, employment
+status, and related compensation information.
+```
+
+**Additional Context**:
+```
+This resource represents the complete employee dataset. Use for querying,
+creating, updating, and managing employee records. Navigation properties
+allow access to related departments, managers, and compensation details.
+```
+
+##### 2. Resource Path and Permissions
+
+**Resource Path**:
+```
+Path: [Relative path to entity set]
+
+Example: `/Employees`
+```
+
+**Complete addressing**:
+```
+Absolute path: [Root URI] + [Resource Path]
+Example: `[https://api.example.com/odata/v4/Employees`](https://api.example.com/odata/v4/Employees`)
+```
+
+**Individual Resource Addressing**:
+```
+Addressing specific resource: [Resource]([Key])
+
+Example: `/Employees('E12345')`
+Example: `/Employees(EmployeeID='E12345')`
+```
+
+**Required Permissions**:
+```
+Read: [Required role]
+Write/Create: [Required role]
+Update: [Required role]
+Delete: [Required role]
+```
+
+**Template**:
+```
+## Resource Information
+
+**Resource Path**: `/Employees`
+
+**Absolute URI**: `[https://api.example.com/odata/v4/Employees`](https://api.example.com/odata/v4/Employees`)
+
+**Key Property**: EmployeeID
+
+**Individual Resource**: `/Employees('E12345')`
+
+**Required Permissions**:
+- Read: ROLE_HR_USER or higher
+- Create: ROLE_HR_MANAGER or higher
+- Update: ROLE_HR_MANAGER or higher
+- Delete: ROLE_ADMIN only
+```
+
+##### 3. Operations Section
+
+Document all operations available on the resource, organized by type:
+
+###### 3.1 CRUD Operations
+
+Standard Create, Read, Update, Delete operations:
+
+| HTTP Method | Action | URI | Description |
+|---|---|---|---|
+| GET | [Read Collection](#operation-get-employees) | `/Employees` | Retrieve all employees |
+| GET | [Read Single](#operation-get-employee) | `/Employees('E12345')` | Retrieve specific employee |
+| POST | [Create](#operation-create-employee) | `/Employees` | Create new employee |
+| PUT | [Replace](#operation-replace-employee) | `/Employees('E12345')` | Replace entire employee |
+| PATCH | [Update](#operation-update-employee) | `/Employees('E12345')` | Partial update employee |
+| DELETE | [Delete](#operation-delete-employee) | `/Employees('E12345')` | Delete employee |
+
+###### 3.2 Custom Operations
+
+Non-standard operations (Actions and Functions):
+
+| Operation Type | Operation Name | URI | Description |
+|---|---|---|---|
+| Function | [Get Manager](#function-get-manager) | `/Employees('E12345')/GetManager()` | Get employee's manager |
+| Function | [Get Reports](#function-get-reports) | `/Employees('E12345')/GetDirectReports()` | Get direct reports |
+| Action | [Promote](#action-promote) | `/Employees('E12345')/Promote` | Promote employee (custom action) |
+| Action | [Deactivate](#action-deactivate) | `/Employees('E12345')/Deactivate` | Deactivate employee (custom action) |
+
+**Formatting**:
+- Operations should be links to detailed operation documentation
+- Include HTTP method, operation name, and URI
+- Separate CRUD from custom operations for clarity
+
+##### 4. Common Headers Section
+
+**Request Headers**:
+| Header Name | Required | Description |
+|---|---|---|
+| Authorization | Yes | Bearer token for authentication |
+| Content-Type | Yes | `application/json` for POST/PUT/PATCH |
+| Accept | No | Preferred response format, default: `application/json` |
+| Prefer | No | OData preferences, e.g., `return=representation` |
+
+**Response Headers**:
+| Header Name | Description |
+|---|---|
+| Content-Type | Response format (application/json) |
+| ETag | Entity tag for optimistic concurrency |
+| Preference-Applied | Indicates which Prefer header was applied |
+
+##### 5. Status and Error Codes Section
+
+| Status Code | Description |
+|---|---|
+| 200 OK | Request successful, response body contains data |
+| 201 Created | Resource successfully created |
+| 204 No Content | Operation successful, no response body (DELETE, update with no return) |
+| 400 Bad Request | Invalid request format or OData query syntax |
+| 401 Unauthorized | Authentication token missing or invalid |
+| 403 Forbidden | Insufficient permissions for operation |
+| 404 Not Found | Resource with specified key doesn't exist |
+| 409 Conflict | Resource already exists or data conflict |
+| 500 Internal Server Error | Server error |
+
+#### Complete OData Resource Template Example
+
+```markdown
+## Employees Resource
+
+Collection of all employees in the system. Provides access to employee master
+data including personal information, organizational assignments, employment
+status, and compensation information.
+
+### Resource Information
+
+**Resource Path**: `/Employees`
+
+**Absolute URI**: `[https://api.example.com/odata/v4/Employees`](https://api.example.com/odata/v4/Employees`)
+
+**Key Property**: EmployeeID
+
+**Individual Resource URI**: `/Employees('E12345')`
+
+**Required Permissions**:
+- Read: ROLE_HR_USER or higher
+- Create: ROLE_HR_MANAGER or higher
+- Update: ROLE_HR_MANAGER or higher
+- Delete: ROLE_ADMIN only
+
+**Resource Properties**:
+- EmployeeID (string): Unique employee identifier
+- FirstName (string): Employee's first name
+- LastName (string): Employee's last name
+- Email (string): Corporate email address
+- HireDate (date): Date employee joined
+- Status (string): Employment status (ACTIVE, INACTIVE, LEAVE)
+- DepartmentID (string): FK to Department
+- ManagerID (string): FK to Manager
+- Salary (decimal): Annual salary
+- CreatedAt (datetime): Resource creation timestamp
+- LastModified (datetime): Last modification timestamp
+
+### Operations
+
+#### CRUD Operations
+
+| HTTP Method | Action | URI |
+|---|---|---|
+| GET | [Retrieve all employees](#get-employees) | `/Employees` |
+| GET | [Retrieve specific employee](#get-single-employee) | `/Employees('{EmployeeID}')` |
+| POST | [Create new employee](#create-employee) | `/Employees` |
+| PUT | [Replace entire employee](#replace-employee) | `/Employees('{EmployeeID}')` |
+| PATCH | [Update employee](#update-employee) | `/Employees('{EmployeeID}')` |
+| DELETE | [Delete employee](#delete-employee) | `/Employees('{EmployeeID}')` |
+
+#### Navigation Properties
+
+| Navigation | Target | Description |
+|---|---|---|
+| Department | Department | Navigate to employee's department |
+| Manager | Employee | Navigate to employee's manager |
+| DirectReports | Employee (collection) | Navigate to direct reports |
+| Compensation | Compensation | Navigate to compensation record |
+
+#### Custom Functions and Actions
+
+| Type | Name | URI | Description |
+|---|---|---|---|
+| Function | GetManager | `/Employees('{EmployeeID}')/GetManager()` | Get employee's direct manager |
+| Function | GetDirectReports | `/Employees('{EmployeeID}')/GetDirectReports()` | Get all direct reports |
+| Function | GetCompensation | `/Employees('{EmployeeID}')/GetCompensation()` | Get compensation details |
+| Action | Promote | `/Employees('{EmployeeID}')/Promote` | Promote employee (requires ROLE_HR_MANAGER) |
+
+### Common Headers
+
+**Request Headers**:
+| Header Name | Required | Description |
+|---|---|---|
+| Authorization | Yes | Bearer token. Format: `Authorization: Bearer {token}` |
+| Content-Type | Yes for POST/PUT/PATCH | Value: `application/json` |
+| Accept | No | Preferred response format. Default: `application/json` |
+| Prefer | No | OData preferences. Example: `return=representation` |
+| If-Match | No | ETag for optimistic concurrency (PUT/PATCH) |
+
+**Response Headers**:
+| Header Name | Description |
+|---|---|
+| Content-Type | Response format: `application/json` |
+| ETag | Entity tag for optimistic concurrency control |
+| Preference-Applied | Indicates which Prefer preference was applied |
+| OData-Version | OData protocol version |
+
+### Status and Error Codes
+
+**Success Codes**:
+| Status Code | Description |
+|---|---|
+| 200 OK | Query successful. Response contains employee data |
+| 201 Created | Employee successfully created. Location header contains new URL |
+| 204 No Content | Operation successful (update/delete). No response body |
+
+**Error Codes**:
+| Status Code | Description |
+|---|---|
+| 400 Bad Request | Invalid OData query syntax or request format |
+| 401 Unauthorized | Authentication token missing, invalid, or expired |
+| 403 Forbidden | Insufficient permissions for operation |
+| 404 Not Found | Employee with specified ID doesn't exist |
+| 409 Conflict | Employee already exists or data constraint violation |
+| 500 Internal Server Error | Server error. Contact support |
+
+### Examples
+
+#### Query all employees:
+```
+GET /Employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer {token}
+Accept: application/json
+```
+
+#### Query with filtering and selection:
+```
+GET /Employees?$filter=Status eq 'ACTIVE' and Department eq 'SALES'&$select=EmployeeID,FirstName,LastName,Email HTTP/1.1
+```
+
+#### Query with paging:
+```
+GET /Employees?$top=50&$skip=100 HTTP/1.1
+```
+
+#### Get specific employee with navigation:
+```
+GET /Employees('E12345')?$expand=Department,Manager HTTP/1.1
+```
+```
+
+---
+
+### OData Operation Template (Level 3)
+
+The Operation Template documents individual operations on OData resources with complete details.
+
+#### Template Sections
+
+##### 1. Title and Introduction
+
+**Format**: Operation Name (HTTP Method + Resource + Operation)
+**Content**: Brief description of the operation
+
+**Examples**:
+- "Create New Employee (POST)"
+- "Get Employee by ID (GET)"
+- "Update Employee (PATCH)"
+- "Get Employee's Manager (Function)"
+
+**Description**:
+```
+Brief summary of what the operation does, what it requires, and what it returns.
+Include business context if relevant.
+```
+
+**Example**:
+```
+Creates a new employee record in the system with provided information.
+Automatically assigns employee ID and initializes default values.
+```
+
+##### 2. Operation Details
+
+**2.1 Operation Description**
+
+Explain when and why to use this operation:
+- Primary use case
+- Important prerequisites
+- Related operations
+- Any special behaviors
+
+**Template**:
+```
+Use this operation to [describe scenario].
+
+Key points:
+- [Important characteristic]
+- [Related operation if applicable]
+- [Performance note if relevant]
+```
+
+##### 3. Request Section
+
+**3.1 URI (Absolute or Relative)**
+
+Complete URI for the operation:
+```
+[HTTP Method] [Path]
+
+Example: POST /Employees
+Example: GET /Employees('E12345')
+Example: PATCH /Employees('E12345')
+```
+
+**3.2 Operation Type**
+
+Classify the operation:
+```
+Operation Type: [CRUD/Function/Action]
+- CRUD: Standard Create, Read, Update, Delete operations
+- Function: Reusable function that returns data
+- Action: Operation that performs business logic
+```
+
+**3.3 HTTP Method**
+
+Exact HTTP method:
+```
+HTTP Method: GET | POST | PUT | PATCH | DELETE
+```
+
+**3.4 Required Permissions**
+
+Who can call this operation:
+```
+Required Permission: [Role or permission level]
+
+Example: ROLE_HR_MANAGER for write operations
+```
+
+**3.5 Request Headers Table**
+
+| Header Name | Required | Possible Values | Description |
+|---|---|---|---|
+| [Header] | [Yes/No] | [Values] | [Description with format/examples] |
+
+**Example**:
+| Header Name | Required | Possible Values | Description |
+|---|---|---|---|
+| Authorization | Yes | `Bearer {token}` | OAuth2 authentication token |
+| Content-Type | Yes (POST/PUT/PATCH) | `application/json` | Media type of request body |
+| Accept | No | `application/json` | Preferred response format |
+| Prefer | No | `return=representation` | Return created resource in response (optional) |
+| If-Match | No | `{ETag}` | ETag for optimistic concurrency (conditional update) |
+
+**3.6 Request Parameters Table**
+
+All parameters passed to the operation:
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| [Name] | Required/Optional | [Type] | [Description with constraints/valid values] | [Path/Query/Body/Header] |
+
+**Organized by Location**:
+
+*Path Parameters* (in URI):
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| EmployeeID | Required | String | Employee unique identifier. Pattern: `E[0-9]{5}` | Path |
+
+*Query Parameters* (for GET with filtering):
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| $filter | Optional | String | OData filter expression. Example: `FirstName eq 'John'` | Query |
+| $orderby | Optional | String | Sort order. Example: `HireDate desc` | Query |
+| $top | Optional | Integer | Maximum records (1-1000). Default: 50 | Query |
+| $skip | Optional | Integer | Records to skip for paging. Default: 0 | Query |
+| $select | Optional | String | Properties to include. Example: `FirstName,LastName,Email` | Query |
+
+*Request Body* (for POST/PUT/PATCH):
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| FirstName | Required | String | Employee's first name (1-50 chars) | Body |
+| LastName | Required | String | Employee's last name (1-50 chars) | Body |
+| Email | Required | String | Corporate email (must be unique) | Body |
+| Department | Required | String | Department code | Body |
+| HireDate | Optional | Date | Hire date (YYYY-MM-DD format) | Body |
+| Salary | Optional | Decimal | Annual salary (min: 20000) | Body |
+
+##### 4. Request Example
+
+Complete request with headers and body:
+
+**Simple GET Request**:
+```http
+GET /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Accept: application/json
+```
+
+**Filtered GET Request**:
+```http
+GET /Employees?$filter=Status eq 'ACTIVE' and Department eq 'SALES'&$select=EmployeeID,FirstName,LastName HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Accept: application/json
+```
+
+**POST Request with Body**:
+```http
+POST /Employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Content-Type: application/json
+
+{
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Salary": 95000.00
+}
+```
+
+**PATCH Request (Partial Update)**:
+```http
+PATCH /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Content-Type: application/json
+If-Match: "abc123def456"
+
+{
+  "Department": "SALES",
+  "Salary": 105000.00
+}
+```
+
+##### 5. Response Section
+
+**5.1 Response Headers Table**
+
+| Header Name | Description | Example Value |
+|---|---|---|
+| Content-Type | Media type of response body | `application/json` |
+| ETag | Entity tag for caching/concurrency | `"abc123def456"` |
+| Location | URL of created/modified resource | `/Employees('E12346')` |
+| OData-Version | OData protocol version | `4.0` |
+
+**5.2 Status and Error Codes Table**
+
+| Status Code | Description | Response Body |
+|---|---|---|
+| 200 OK | [Success description] | [Entity or data returned] |
+| 201 Created | [Success description] | [Entity in response] |
+| 204 No Content | [Success description] | Empty body |
+| 400 Bad Request | [Error description] | Error details |
+| 401 Unauthorized | [Error description] | Error message |
+
+**5.3 Response Payload Example**
+
+Success response body with actual data structure:
+
+```json
+{
+  "EmployeeID": "E12346",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Status": "ACTIVE",
+  "Salary": 95000.00,
+  "CreatedAt": "2024-01-15T10:30:00Z",
+  "LastModified": "2024-01-15T10:30:00Z",
+  "Department@odata.navigationLink": "[https://api.example.com/odata/v4/Departments('ENG](https://api.example.com/odata/v4/Departments('ENG)')",
+  "Manager@odata.navigationLink": "[https://api.example.com/odata/v4/Employees('E10001](https://api.example.com/odata/v4/Employees('E10001)')"
+}
+```
+
+##### 6. Complete Response Example with Headers
+
+**For POST (201 Created)**:
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: [https://api.example.com/odata/v4/Employees('E12346](https://api.example.com/odata/v4/Employees('E12346)')
+ETag: "abc123def456"
+OData-Version: 4.0
+
+{
+  "EmployeeID": "E12346",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Status": "ACTIVE",
+  "Salary": 95000.00,
+  "CreatedAt": "2024-01-15T10:30:00Z"
+}
+```
+
+**For GET (200 OK)**:
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+ETag: "abc123def456"
+OData-Version: 4.0
+
+{
+  "EmployeeID": "E12345",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "Salary": 95000.00,
+  "Status": "ACTIVE"
+}
+```
+
+**For Error Response (400 Bad Request)**:
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "INVALID_DATA",
+    "message": "Request body validation failed",
+    "details": [
+      {
+        "field": "Email",
+        "issue": "Email already exists",
+        "value": "john.doe@company.com"
+      },
+      {
+        "field": "Salary",
+        "issue": "Minimum salary is 20000",
+        "value": "15000"
+      }
+    ]
+  }
+}
+```
+
+#### Complete OData Operation Template Example
+
+```markdown
+### Create New Employee (POST)
+
+Creates a new employee record in the system with provided information.
+Automatically assigns unique employee ID and initializes default values
+(status: ACTIVE, creation timestamp).
+
+#### Usage
+
+Use this operation when adding a new employee to the system. Required fields
+include first name, last name, email, and department. Optional fields like
+hire date and salary can be provided.
+
+Key points:
+- Automatically generates unique EmployeeID
+- Email must be unique across system
+- Returns created employee in response body (if Prefer header included)
+- Triggers HR workflow notifications
+- Related operations: PATCH for updates, GET for retrieval
+
+#### Request
+
+**URI**: POST /Employees
+
+**Operation Type**: CRUD (Create)
+
+**HTTP Method**: POST
+
+**Required Permission**: ROLE_HR_MANAGER or ROLE_ADMIN
+
+#### Request Headers
+
+| Header Name | Required | Possible Values | Description |
+|---|---|---|---|
+| Authorization | Yes | `Bearer {token}` | OAuth2 authentication token required |
+| Content-Type | Yes | `application/json` | Media type of request body |
+| Accept | No | `application/json` | Preferred response format |
+| Prefer | No | `return=representation` | Return created resource in response (optional) |
+
+#### Request Parameters
+
+**Request Body Parameters** (all in JSON body):
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| FirstName | Required | String | Employee's first name. Length: 1-50 characters | Body |
+| LastName | Required | String | Employee's last name. Length: 1-50 characters | Body |
+| Email | Required | String | Corporate email. Must be unique. Format: valid email address | Body |
+| Department | Required | String | Department code. Example: "ENGINEERING" | Body |
+| HireDate | Optional | Date | Hire date in YYYY-MM-DD format. Example: "2024-01-15" | Body |
+| Salary | Optional | Decimal | Annual salary in USD. Minimum: 20000. Example: 95000.00 | Body |
+| Status | Optional | String | Employment status. Default: "ACTIVE". Valid: "ACTIVE", "INACTIVE", "LEAVE" | Body |
+
+#### Request Example
+
+```http
+POST /Employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+Prefer: return=representation
+
+{
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Salary": 95000.00
+}
+```
+
+#### Response
+
+**Response Headers**:
+
+| Header Name | Description | Example Value |
+|---|---|---|
+| Content-Type | Response body media type | `application/json` |
+| Location | URL of newly created employee | `[https://api.example.com/odata/v4/Employees('E12346](https://api.example.com/odata/v4/Employees('E12346)')` |
+| ETag | Entity tag for caching/concurrency | `"abc123def456"` |
+| OData-Version | OData protocol version | `4.0` |
+
+**Status Codes**:
+
+| Status Code | Description |
+|---|---|
+| 201 Created | Employee successfully created. Location header contains URL to new resource |
+| 400 Bad Request | Validation failed. Email might already exist or missing required fields |
+| 401 Unauthorized | Authentication token missing, invalid, or expired |
+| 403 Forbidden | Insufficient permissions. Requires ROLE_HR_MANAGER or higher |
+| 409 Conflict | Employee with email already exists in system |
+| 500 Internal Server Error | Server error. Contact support if issue persists |
+
+**Response Payload Example** (201 Created):
+
+```json
+{
+  "EmployeeID": "E12346",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Status": "ACTIVE",
+  "Salary": 95000.00,
+  "CreatedAt": "2024-01-15T10:30:00Z",
+  "LastModified": "2024-01-15T10:30:00Z"
+}
+```
+
+**Complete Response Example**:
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: [https://api.example.com/odata/v4/Employees('E12346](https://api.example.com/odata/v4/Employees('E12346)')
+ETag: "abc123def456"
+OData-Version: 4.0
+
+{
+  "EmployeeID": "E12346",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Status": "ACTIVE",
+  "Salary": 95000.00,
+  "CreatedAt": "2024-01-15T10:30:00Z",
+  "LastModified": "2024-01-15T10:30:00Z"
+}
+```
+
+**Error Response Example** (400 Bad Request):
+
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Request validation failed. See details for specific errors",
+    "details": [
+      {
+        "field": "Email",
+        "issue": "Email already exists in system",
+        "value": "john.doe@company.com",
+        "existingEmployeeId": "E10001"
+      },
+      {
+        "field": "Salary",
+        "issue": "Salary must be at least 20000",
+        "value": "15000"
+      }
+    ]
+  }
+}
+```
+
+**Error Response Example** (409 Conflict):
+
+```http
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "DUPLICATE_EMPLOYEE",
+    "message": "Employee with email john.doe@company.com already exists",
+    "details": {
+      "existingEmployeeId": "E10001",
+      "existingEmployeeName": "John Doe",
+      "email": "john.doe@company.com"
+    }
+  }
+}
+```
+```
+
+#### OData Operation Template Checklist
+
+- [ ] Title (operation type + resource + operation name)
+- [ ] Introduction/description
+- [ ] Usage section with key points
+- [ ] Request URI (absolute or relative)
+- [ ] Operation type (CRUD/Function/Action)
+- [ ] HTTP method
+- [ ] Required permissions
+- [ ] Request headers table with requirement status
+- [ ] Request parameters table with data type and location
+- [ ] Complete request example with headers and body
+- [ ] Response headers table
+- [ ] Status codes with descriptions
+- [ ] Response payload example (JSON structure)
+- [ ] Complete response example with headers
+- [ ] Error response example(s)
+
+---
+
+### OData API Templates - Usage Guidelines
+
+#### Three-Level Organization
+
+**Level 1 - Service Overview**:
+- Use for overview of an entire OData service
+- Contains service purpose, metadata, supported OData versions
+- Lists all available resources with links
+- Documents OData feature support matrix
+- Appropriate for entire service documentation
+
+**Level 2 - Resource Documentation**:
+- Use for individual resources/entity sets within the service
+- Contains resource-specific information
+- Lists all operations on the resource (CRUD and custom)
+- Links to detailed operation documentation
+- Organizes navigation properties and relationships
+
+**Level 3 - Operation Details**:
+- Use for documenting single operations on resources
+- Contains operation-specific request/response information
+- Includes request parameters, headers, status codes
+- Provides complete request/response examples
+- Detailed error handling and edge cases
+
+#### Best Practices for OData Templates
+
+1. **Hierarchical Organization**
+   - Structure documentation from broad service down to granular operations
+   - Service overview → Resource → Operation
+   - Each level references next through links
+   - Users navigate from general to specific information
+
+2. **Contextual Information at Each Level**
+
+   **Service Level**:
+   - Overall service purpose
+   - Supported OData versions and features
+   - Service metadata endpoint
+   - Permissions required across service
+   - Entity relationships and data model
+
+   **Resource Level**:
+   - Resource-specific permissions
+   - All operations on resource (CRUD + custom)
+   - Navigation properties
+   - Links to detailed operation docs
+
+   **Operation Level**:
+   - Operation-specific details
+   - Exact request/response format
+   - Complete working examples
+   - Error scenarios with examples
+
+3. **Clear Cross-Linking**
+   - Service overview links to resources
+   - Resources link to operations
+   - Operations link back to resources/service
+   - Related operations cross-referenced
+
+4. **Complete Filtering Examples**
+   - Show $filter syntax examples
+   - Document filter operators supported
+   - Explain navigation expansion ($expand)
+   - Demonstrate paging ($top, $skip)
+   - Show property selection ($select)
+
+5. **Navigation Property Documentation**
+   - List all navigation properties per resource
+   - Show how to expand relationships
+   - Document related resources
+   - Include examples of navigation URIs
+
+6. **Consistent Terminology**
+   - Use exact property names from metadata
+   - Match terminology across levels
+   - Explain OData-specific concepts
+   - Define custom functions/actions clearly
+
+7. **Real Working Examples**
+   - Every operation should have working examples
+   - Show request with headers and body
+   - Include complete response with headers
+   - Demonstrate error scenarios
+   - Use realistic data matching property types
+
+8. **Error Handling**
+   - Document all possible status codes per operation
+   - Provide context-specific error descriptions
+   - Include error response examples
+   - Explain how to handle and recover from errors
+
+---
+
+## TEMPLATE COMPARISON TABLE
+
+### REST vs OData Structure
+
+| Aspect | REST | OData |
+|--------|------|-------|
+| **Hierarchy** | 2 levels: Overview + Method | 3 levels: Service + Resource + Operation |
+| **Entity Naming** | Plural (e.g., `/employees`) | Entity Set (e.g., `/Employees`) |
+| **Documentation Structure** | Resource-focused | Service-focused with deep hierarchy |
+| **Filtering** | Custom query parameters | Standardized OData $filter, $orderby |
+| **Paging** | limit/offset or page params | $top, $skip parameters |
+| **Selection** | Custom implementation | $select parameter (standard) |
+| **Navigation** | Via nested endpoints | Via $expand property (standard) |
+| **Metadata** | Optional, no standard location | Required at $metadata endpoint |
+| **Status Code Usage** | Full range (2xx, 3xx, 4xx, 5xx) | Primarily 200, 201, 400, 401, 403, 404, 500 |
+| **Best Use Case** | General-purpose APIs | Data-centric services and entity operations |
+| **Version Support** | N/A | Multiple versions (2.0, 3.0, 4.0) |
+
+### Template Requirements Comparison
+
+| Requirement | REST Overview | REST Method | OData Service | OData Resource | OData Operation |
+|---|---|---|---|---|---|
+| Base URI | Required | Inherited | Required | Inherited | Inherited |
+| Permissions | Required | Optional | Required | Required | Required |
+| Status Codes | Complete list | Per-method | General list | General list | Per-operation |
+| Parameters table | N/A | Required | N/A | N/A | Required |
+| Examples | Optional | Highly recommended | N/A | Suggested | Required |
+| Metadata reference | N/A | N/A | Required | Optional | N/A |
+| Navigation info | N/A | N/A | Listed | Links table | References |
+| OData features | N/A | N/A | Support matrix | N/A | N/A |
+
+---
+
+## BEST PRACTICES
+
+### Documentation Quality Standards
+
+1. **Completeness**
+   - Document every method/operation
+   - Include all status codes with context
+   - Provide request and response examples
+   - Explain error scenarios
+
+2. **Clarity**
+   - Use simple, direct language
+   - Avoid technical jargon without explanation
+   - Provide context for business logic
+   - Explain constraints and limitations
+
+3. **Consistency**
+   - Follow template structure exactly
+   - Use consistent terminology throughout
+   - Maintain consistent formatting
+   - Organize information predictably
+
+4. **Accuracy**
+   - Verify all examples work as documented
+   - Keep parameter information current
+   - Update when API behavior changes
+   - Test scenarios before documenting
+
+5. **Navigation**
+   - Provide clear links between levels
+   - Help users find related information
+   - Cross-reference related operations
+   - Use consistent anchor names
+
+### Template Customization Guidelines
+
+These are generic templates that should be customized:
+
+1. **Remove Irrelevant Sections**
+   - If API doesn't use authentication, simplify permission docs
+   - If no custom headers, remove from template
+   - If no custom functions/actions, remove from OData resource
+
+2. **Add Missing Details**
+   - Include any API-specific features
+   - Add custom headers or parameters unique to your API
+   - Document business rules specific to your service
+   - Include rate limits, quotas, or special constraints
+
+3. **Organize by Your Structure**
+   - Group related methods logically
+   - Use categories that match your service design
+   - Include index/navigation appropriate for your docs
+   - Reference your actual service endpoints
+
+4. **Match Your Standards**
+   - Use your company's style guide
+   - Follow your documentation conventions
+   - Match your existing documentation structure
+   - Incorporate your terminology
+
+### Common Pitfalls to Avoid
+
+1. **Incomplete Examples**
+   - Always include complete request with headers
+   - Show both success and error responses
+   - Use realistic, non-dummy data
+   - Include actual status codes
+
+2. **Generic Status Descriptions**
+   - Not just "400 Bad Request"
+   - Explain what was wrong with this operation
+   - Provide guidance on how to fix
+   - Use operation-specific context
+
+3. **Missing Parameter Details**
+   - Always include parameter location (Path/Query/Body)
+   - Document constraints (min/max, format, valid values)
+   - Explain defaults
+   - Show example values
+
+4. **Undocumented Relationships**
+   - For OData: List all navigation properties
+   - Show examples of navigation URIs
+   - Explain cardinality (one-to-one, one-to-many)
+   - Document expansion examples
+
+5. **Unclear Permission Requirements**
+   - Be specific about required roles
+   - Explain why permission is needed
+   - Note if different operations need different permissions
+   - Provide guidance for permission assignment
+
+6. **Missing Error Cases**
+   - Document ALL possible error codes
+   - Explain conditions that trigger each error
+   - Provide examples of error responses
+   - Explain how to handle and prevent errors
+
+---
+
+## COMPLETE WORKING EXAMPLES
+
+### Complete REST API Documentation Example
+
+**File**: employees-rest-api.md
+
+```markdown
+# Employees REST API
+
+Complete REST API for managing employee records in the company system.
+
+## Base Information
+
+**Base URI**: `[https://api.example.com/v1/employees`](https://api.example.com/v1/employees`)
+
+**Permissions**:
+- Read: ROLE_HR_USER
+- Write/Delete: ROLE_HR_MANAGER
+- Admin: ROLE_ADMIN
+
+## Methods
+
+| HTTP Method | Action | URI |
+|---|---|---|
+| GET | [List Employees](#list-employees) | `/employees` |
+| GET | [Get Employee](#get-employee) | `/employees/{employeeId}` |
+| POST | [Create Employee](#create-employee) | `/employees` |
+| PATCH | [Update Employee](#update-employee) | `/employees/{employeeId}` |
+| DELETE | [Delete Employee](#delete-employee) | `/employees/{employeeId}` |
+
+## Common Request Headers
+
+| Header Name | Required | Description |
+|---|---|---|
+| Authorization | Yes | Bearer token. Format: `Authorization: Bearer {token}` |
+| Content-Type | Yes | `application/json` |
+| Accept | No | Preferred format. Default: `application/json` |
+
+## Common Response Headers
+
+| Header Name | Description |
+|---|---|
+| Content-Type | Always `application/json` |
+| X-Total-Count | Total available records for paginated queries |
+| ETag | Entity version for caching |
+
+## Status Codes
+
+| Status Code | Description |
+|---|---|
+| 200 OK | Success with response body |
+| 201 Created | Resource created successfully |
+| 204 No Content | Success without response body |
+| 400 Bad Request | Invalid request format |
+| 401 Unauthorized | Authentication required |
+| 404 Not Found | Resource doesn't exist |
+| 409 Conflict | Resource conflict (duplicate) |
+| 500 Internal Server Error | Server error |
+
+---
+
+## List Employees
+
+Returns paginated list of all employees.
+
+GET /employees
+
+### Parameters
+
+| Name | Required | Type | Description | Location |
+|---|---|---|---|---|
+| limit | No | Integer | Results per page (1-100, default 20) | Query |
+| offset | No | Integer | Records to skip (default 0) | Query |
+| department | No | String | Filter by department code | Query |
+| status | No | String | Filter by status (ACTIVE, INACTIVE, LEAVE) | Query |
+
+### Request Example
+
+```
+GET /employees?limit=50&offset=0&status=ACTIVE HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Accept: application/json
+```
+
+### Response
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+X-Total-Count: 5000
+
+{
+  "employees": [
+    {
+      "employeeId": "E12345",
+      "firstName": "John",
+      "lastName": "Doe",
+      "email": "john@example.com",
+      "department": "ENGINEERING",
+      "status": "ACTIVE"
+    },
+    {
+      "employeeId": "E12346",
+      "firstName": "Jane",
+      "lastName": "Smith",
+      "email": "jane@example.com",
+      "department": "SALES",
+      "status": "ACTIVE"
+    }
+  ],
+  "pagination": {
+    "limit": 50,
+    "offset": 0,
+    "total": 5000
+  }
+}
+```
+
+---
+
+## Get Employee
+
+Retrieves complete employee details by ID.
+
+GET /employees/{employeeId}
+
+### Parameters
+
+| Name | Required | Type | Description | Location |
+|---|---|---|---|---|
+| employeeId | Yes | String | Employee ID (E[0-9]{5}) | Path |
+
+### Request Example
+
+```
+GET /employees/E12345 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Accept: application/json
+```
+
+### Response
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "employeeId": "E12345",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john@example.com",
+  "department": "ENGINEERING",
+  "jobTitle": "Senior Engineer",
+  "hireDate": "2020-06-01",
+  "salary": 120000,
+  "status": "ACTIVE",
+  "manager": {
+    "employeeId": "E10001",
+    "name": "Jane Smith"
+  },
+  "createdAt": "2020-06-01T09:00:00Z",
+  "lastModified": "2024-01-15T14:30:00Z"
+}
+```
+
+### Error Response (404 Not Found)
+
+```
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Employee E99999 not found"
+  }
+}
+```
+
+---
+
+## Create Employee
+
+Creates a new employee record.
+
+POST /employees
+
+### Parameters
+
+| Name | Required | Type | Description | Location |
+|---|---|---|---|---|
+| firstName | Yes | String | First name (1-50 chars) | Body |
+| lastName | Yes | String | Last name (1-50 chars) | Body |
+| email | Yes | String | Unique email address | Body |
+| department | Yes | String | Department code | Body |
+| jobTitle | Yes | String | Job title | Body |
+| hireDate | No | Date | Hire date (YYYY-MM-DD) | Body |
+| salary | No | Decimal | Annual salary (min: 20000) | Body |
+
+### Request Example
+
+```
+POST /employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Content-Type: application/json
+
+{
+  "firstName": "Michael",
+  "lastName": "Johnson",
+  "email": "michael@example.com",
+  "department": "SALES",
+  "jobTitle": "Sales Manager",
+  "hireDate": "2024-01-15",
+  "salary": 95000
+}
+```
+
+### Response
+
+```
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: [https://api.example.com/v1/employees/E12347](https://api.example.com/v1/employees/E12347)
+
+{
+  "employeeId": "E12347",
+  "firstName": "Michael",
+  "lastName": "Johnson",
+  "email": "michael@example.com",
+  "department": "SALES",
+  "jobTitle": "Sales Manager",
+  "hireDate": "2024-01-15",
+  "salary": 95000,
+  "status": "ACTIVE",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+### Error Response (409 Conflict)
+
+```
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "DUPLICATE_EMAIL",
+    "message": "Email already exists",
+    "details": {
+      "email": "michael@example.com",
+      "existingEmployeeId": "E10001"
+    }
+  }
+}
+```
+
+---
+
+## Update Employee
+
+Updates employee information (partial update).
+
+PATCH /employees/{employeeId}
+
+### Parameters
+
+| Name | Required | Type | Description | Location |
+|---|---|---|---|---|
+| employeeId | Yes | String | Employee ID | Path |
+| Any field | No | Various | Fields to update (firstName, lastName, department, etc) | Body |
+
+### Request Example
+
+```
+PATCH /employees/E12345 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+Content-Type: application/json
+
+{
+  "department": "SALES",
+  "jobTitle": "Sales Director",
+  "salary": 130000
+}
+```
+
+### Response
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "employeeId": "E12345",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john@example.com",
+  "department": "SALES",
+  "jobTitle": "Sales Director",
+  "salary": 130000,
+  "status": "ACTIVE",
+  "lastModified": "2024-01-20T15:45:00Z"
+}
+```
+
+---
+
+## Delete Employee
+
+Marks employee as inactive (soft delete).
+
+DELETE /employees/{employeeId}
+
+### Parameters
+
+| Name | Required | Type | Description | Location |
+|---|---|---|---|---|
+| employeeId | Yes | String | Employee ID | Path |
+
+### Request Example
+
+```
+DELETE /employees/E12346 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### Response
+
+```
+HTTP/1.1 204 No Content
+```
+
+### Error Response (403 Forbidden)
+
+```
+HTTP/1.1 403 Forbidden
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "INSUFFICIENT_PERMISSION",
+    "message": "Only admins can delete employees",
+    "requiredRole": "ROLE_ADMIN",
+    "yourRole": "ROLE_HR_MANAGER"
+  }
+}
+```
+```
+
+### Complete OData API Documentation Example
+
+**File**: employees-odata-service.md
+
+```markdown
+# Employees OData Service
+
+Comprehensive OData v4 service for employee data management.
+
+## Overview
+
+**OData Version**: 4.0
+
+**Root URI**: `[https://api.example.com/odata/v4`](https://api.example.com/odata/v4`)
+
+**Permissions**:
+- Read: ROLE_HR_USER
+- Write: ROLE_HR_MANAGER
+- Admin: ROLE_ADMIN
+
+## OData Features
+
+| Feature | Supported | Notes |
+|---|---|---|
+| $filter | Yes | All comparison operators |
+| $orderby | Yes | Single and multi-field |
+| $top/$skip | Yes | Max 1000 per request |
+| $select | Yes | Choose specific properties |
+| $expand | Yes | Limited to 3 levels |
+| $count | Yes | Get total count |
+
+## Entity Data Model
+
+**Employees**: Employee personal and employment data
+**Departments**: Organization structure
+**Compensation**: Salary and benefits
+
+## Resources
+
+| Resource | Description | Path |
+|---|---|---|
+| [Employees](#employees-resource) | All employees | `/Employees` |
+| [Departments](#departments-resource) | Organization | `/Departments` |
+
+---
+
+## Employees Resource
+
+Collection of all employees.
+
+### Resource Information
+
+**Path**: `/Employees`
+
+**Key**: EmployeeID
+
+**Permissions**:
+- Read: ROLE_HR_USER
+- Write: ROLE_HR_MANAGER
+
+### Operations
+
+| Method | Action | URI |
+|---|---|---|
+| GET | Query all | `/Employees` |
+| GET | Get one | `/Employees('E12345')` |
+| POST | Create | `/Employees` |
+| PATCH | Update | `/Employees('E12345')` |
+| DELETE | Delete | `/Employees('E12345')` |
+
+### Examples
+
+#### Query employees:
+
+```
+GET /Employees?$filter=Status eq 'ACTIVE'&$orderby=LastName HTTP/1.1
+Host: api.example.com
+Authorization: Bearer {token}
+
+Response (200 OK):
+{
+  "value": [
+    {
+      "EmployeeID": "E12345",
+      "FirstName": "John",
+      "LastName": "Doe",
+      "Email": "john@example.com",
+      "Status": "ACTIVE"
+    }
+  ]
+}
+```
+
+#### Create employee:
+
+```
+POST /Employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer {token}
+Content-Type: application/json
+Prefer: return=representation
+
+{
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john@example.com",
+  "Department": "ENGINEERING"
+}
+
+Response (201 Created):
+{
+  "EmployeeID": "E12346",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john@example.com",
+  "Department": "ENGINEERING",
+  "Status": "ACTIVE",
+  "CreatedAt": "2024-01-15T10:30:00Z"
+}
+```
+
+#### Update employee:
+
+```
+PATCH /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "Department": "SALES"
+}
+
+Response (204 No Content):
+```
+```
+
+---
+
+## FIELD-BY-FIELD REQUIREMENTS
+
+### REST API Overview Template Fields
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| Title | Yes | String | API name |
+| Introduction | Yes | String | Brief description |
+| Base URI | Yes | String | Absolute endpoint URL |
+| Permissions | Yes | List | Required roles/permissions |
+| Methods Table | Yes | Table | All HTTP methods + URIs |
+| Request Headers Table | Conditional | Table | Document if headers used |
+| Response Headers Table | Conditional | Table | Document if headers returned |
+| Status Codes Table | Yes | Table | All possible response codes |
+
+### REST API Method Template Fields
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| Title | Yes | String | Action + Resource |
+| Introduction | Yes | String | What method does |
+| Usage | Yes | String | When/why to use |
+| HTTP Method | Yes | Enum | GET, POST, PUT, PATCH, DELETE |
+| URI Path | Yes | String | Relative or absolute |
+| Permission | Yes | String | Required role |
+| Parameters Table | Conditional | Table | If parameters exist |
+| Request Example | Yes | Code Block | Complete with headers |
+| Status Codes | Yes | Table | Per-method codes |
+| Response Body | Yes | JSON/Code | Example response |
+| Response Example | Yes | Code Block | Full response with headers |
+| Error Examples | Yes | Code Block | At least one error case |
+
+### OData Service Overview Template Fields
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| Title | Yes | String | Service name |
+| Introduction | Yes | String | Service purpose |
+| OData Version | Yes | String | 2.0, 3.0, or 4.0 |
+| Root URI | Yes | String | Service endpoint |
+| Permissions | Yes | List | Required roles |
+| Feature Support Matrix | Yes | Table | Supported OData features |
+| Entity Data Model | Yes | Description/Diagram | Data structure |
+| Service Metadata URI | Yes | String | $metadata endpoint |
+| Resources Table | Yes | Table | Available entity sets |
+
+### OData Resource Template Fields
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| Title | Yes | String | Resource name |
+| Introduction | Yes | String | Resource purpose |
+| Resource Path | Yes | String | Entity set path |
+| Absolute URI | Yes | String | Complete endpoint |
+| Key Property | Yes | String | Identifier property |
+| Permissions | Yes | List | Per-operation permissions |
+| CRUD Operations Table | Yes | Table | GET, POST, PUT, PATCH, DELETE |
+| Navigation Properties | Conditional | Table | If applicable |
+| Custom Operations | Conditional | Table | Functions/Actions |
+| Common Headers | Yes | Table | Request/response headers |
+| Status Codes | Yes | Table | All possible codes |
+
+### OData Operation Template Fields
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| Title | Yes | String | Operation name + type |
+| Introduction | Yes | String | Operation purpose |
+| Description | Yes | String | When/why to use |
+| URI | Yes | String | Full operation path |
+| Operation Type | Yes | Enum | CRUD, Function, Action |
+| HTTP Method | Yes | Enum | GET, POST, PUT, PATCH, DELETE |
+| Permission | Yes | String | Required role |
+| Request Headers | Yes | Table | All headers |
+| Request Parameters | Yes | Table | With location info |
+| Request Example | Yes | Code Block | Complete HTTP request |
+| Response Headers | Yes | Table | Response headers |
+| Status Codes | Yes | Table | Per-operation codes |
+| Response Body | Yes | JSON | Example response data |
+| Response Example | Yes | Code Block | Full response with headers |
+| Error Examples | Conditional | Code Block | Common error cases |
+
+---
+
+## HIERARCHICAL LINKING GUIDANCE
+
+### REST API Linking Strategy
+
+**Level 1 (Overview) → Level 2 (Methods)**
+
+In Overview document:
+```markdown
+## Methods
+
+| HTTP Method | Action | URI |
+|---|---|---|
+| GET | [List all employees](#list-employees) | `/employees` |
+| GET | [Get employee by ID](#get-employee-by-id) | `/employees/{employeeId}` |
+| POST | [Create employee](#create-employee) | `/employees` |
+| PATCH | [Update employee](#update-employee) | `/employees/{employeeId}` |
+| DELETE | [Delete employee](#delete-employee) | `/employees/{employeeId}` |
+```
+
+In Method documents (Level 2):
+```markdown
+## Update Employee
+
+*See parent documentation*: [Employees REST API](#employees-rest-api)
+
+*Related methods*:
+- [Get Employee](#get-employee)
+- [List Employees](#list-employees)
+```
+
+### OData Linking Strategy
+
+**Level 1 (Service) → Level 2 (Resources) → Level 3 (Operations)**
+
+In Service Overview (Level 1):
+```markdown
+## Resources
+
+| Resource Name | Description | Path |
+|---|---|---|
+| [Employees](#employees-resource) | All employees | `/Employees` |
+| [Departments](#departments-resource) | Departments | `/Departments` |
+```
+
+In Resource Document (Level 2):
+```markdown
+## Employees Resource
+
+*Parent*: [Employees OData Service](#employees-odata-service)
+
+### Operations
+
+| Method | Operation | URI |
+|---|---|---|
+| GET | [Query all](#odata-operation-query-employees) | `/Employees` |
+| POST | [Create](#odata-operation-create-employee) | `/Employees` |
+```
+
+In Operation Document (Level 3):
+```markdown
+## Create Employee (POST)
+
+**Resource**: [Employees](#employees-resource)
+
+**Service**: [Employees OData Service](#employees-odata-service)
+
+**Related Operations**:
+- [Query Employees](#operation-query-employees)
+- [Get Employee](#operation-get-single-employee)
+- [Update Employee](#operation-update-employee)
+```
+
+### Anchor Naming Conventions
+
+**For Consistency and Reliability:**
+
+- REST Overview: `#rest-api-[resource-name]`
+  - Example: `#rest-api-employees`
+
+- REST Methods: `#[verb]-[resource]` or `#[operation-name]`
+  - Example: `#list-employees`, `#create-employee`, `#get-employee-by-id`
+
+- OData Service: `#odata-service-[service-name]`
+  - Example: `#odata-service-employees`
+
+- OData Resource: `#odata-resource-[resource-name]`
+  - Example: `#odata-resource-employees`
+
+- OData Operation: `#odata-operation-[action]`
+  - Example: `#odata-operation-create-employee`, `#odata-operation-query-employees`
+
+### Cross-Document Linking
+
+**When Documentation Spans Multiple Files:**
+
+Use absolute paths:
+```markdown
+See [Employees REST API](../rest-apis/employees.md#rest-api-employees)
+for complete REST method documentation.
+```
+
+Or use markdown anchor syntax:
+```markdown
+See [Employees REST API](rest-apis/employees.md) for complete REST documentation.
+```
+
+---
+
+## REFERENCES & OFFICIAL STANDARDS
+
+**Official SAP API Style Guide Section 50**:
+[https://github.com/SAP-docs/api-style-guide/tree/main/docs/50-manually-written-rest-and-odata](https://github.com/SAP-docs/api-style-guide/tree/main/docs/50-manually-written-rest-and-odata)
+
+**Individual Files Consolidated:**
+1. manually-written-rest-and-odata-api-reference-49b7204.md - Overview
+2. rest-api-overview-template-e888f14.md - REST Level 1 Template
+3. rest-api-method-template-d48b7e8.md - REST Level 2 Template
+4. using-rest-api-templates-b393567.md - REST Usage Guidelines
+5. odata-service-overview-template-d47f0cb.md - OData Level 1 Template
+6. odata-resource-template-745fbaa.md - OData Level 2 Template
+7. odata-operation-template-d7d9b26.md - OData Level 3 Template
+8. using-odata-api-templates-49a7cd7.md - OData Usage Guidelines
+
+**Related SAP Documentation**:
+- [Section 30 - REST and OData API Documentation](https://github.com/SAP-docs/api-style-guide/tree/main/docs/30-rest-and-odata-api-documentation)
+- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
+- [OData Specification](https://www.odata.org/documentation/)
+- [SAP API Business Hub](https://api.sap.com/)
+
+**Last Verified**: 2025-11-21
+
+**Compliance**: Follows official SAP API Style Guide standards for manual REST and OData API documentation
+
+---
+
+**End of Manual REST and OData API Documentation Templates Guide**
diff --git a/references/naming-conventions.md b/references/naming-conventions.md
new file mode 100644
index 0000000..f4e1547
--- /dev/null
+++ b/references/naming-conventions.md
@@ -0,0 +1,2059 @@
+# API Naming Conventions Reference
+
+**Source**: SAP API Style Guide v2021.01 | [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide)
+
+**Last Updated**: 2025-11-21
+
+**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))
+
+**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates.
+
+**Scope**: REST APIs, OData APIs, Java, JavaScript, .NET, and C/C++ libraries
+
+---
+
+## Table of Contents
+
+1. [Core Naming Principles](#core-naming-principles)
+2. [General API Naming Rules](#general-api-naming-rules)
+3. [Word Combination Conventions](#word-combination-conventions)
+4. [Acronym Guidelines](#acronym-guidelines)
+5. [REST and OData Naming](#rest-and-odata-naming)
+6. [Native Library Naming](#native-library-naming)
+7. [Common Mistakes to Avoid](#common-mistakes-to-avoid)
+8. [Reference Tables](#reference-tables)
+9. [Naming Decision Trees](#naming-decision-trees)
+10. [Best Practices Summary](#best-practices-summary)
+
+---
+
+## Core Naming Principles
+
+### 1. Clarity and Consistency
+
+**Principle**: Names must be immediately understandable to developers without requiring additional context.
+
+- Use correctly spelled American English words
+- Avoid ambiguous abbreviations
+- Maintain consistent terminology across entire API
+- Use meaningful, descriptive names (not single letters except in loops)
+
+**Example - Clarity**:
+```
+✅ GOOD:   orders, customerAddress, createInvoice
+❌ BAD:    o, cAddr, ci
+❌ BAD:    usr_acct (mixed conventions), CUSTOMR (misspelled)
+```
+
+### 2. Language-Specific Conventions
+
+**Principle**: Names must follow established conventions for their specific language/platform.
+
+| Language | Convention | Scope |
+|----------|-----------|-------|
+| REST/OData URI | kebab-case or lowerCamelCase | Resource names, query parameters |
+| Java | lowerCamelCase (methods), UpperCamelCase (classes) | Methods, packages, interfaces |
+| JavaScript | lowerCamelCase (methods), UpperCamelCase (classes) | Functions, classes, namespaces |
+| .NET | UpperCamelCase (methods), UpperCamelCase (classes) | Methods, classes, namespaces |
+| C/C++ | lowercase_with_underscores (functions) | Functions, macros, enums |
+
+### 3. Grammatical Correctness
+
+**Principle**: Names should follow proper English grammar rules.
+
+- Use nouns for entities: `customer`, `order`, `product`
+- Use verbs for actions: `create`, `update`, `delete`, `validate`
+- Use adjectives for attributes: `active`, `archived`, `disabled`
+- Complete phrases are better than fragments
+
+**Example - Grammar**:
+```
+✅ GOOD:   isActive, getCustomerByID, updateOrderStatus
+❌ BAD:    activ (incomplete), getcustomer (no camelCase), order_updated (past tense for getter)
+```
+
+### 4. Avoidance of Implementation Details
+
+**Principle**: Names should reflect intent and business purpose, not technical implementation.
+
+- Don't expose internal architecture in names
+- Don't use technology-specific terms in business-facing APIs
+- Names should remain valid even if implementation changes
+
+**Example - Implementation Details**:
+```
+✅ GOOD:   getEmployeeData (what it does)
+❌ BAD:    getEmployeeDataFromDatabase (reveals implementation)
+❌ BAD:    fetchXmlResponse (technical details)
+```
+
+---
+
+## General API Naming Rules
+
+### API Name Rules
+
+**Rule 1: Don't Include "API" in the Name**
+
+- The word "API" is implied by context
+- Adding "API" is redundant and clutters naming
+
+**Examples**:
+```
+✅ GOOD:   "Customer Orders"
+❌ BAD:    "Customer Orders API"
+❌ BAD:    "Customer Orders APIs"
+
+✅ GOOD:   "Employee Management"
+❌ BAD:    "Employee Management REST API"
+```
+
+**Rule 2: Capitalize Words Properly**
+
+- Use Title Case for multi-word API names
+- Capitalize each significant word
+- Maintain consistent capitalization throughout documentation
+
+**Examples**:
+```
+✅ GOOD:   "Purchase Order Processing"
+❌ BAD:    "purchase order processing" (all lowercase)
+❌ BAD:    "Purchase order processing" (inconsistent)
+❌ BAD:    "PURCHASE ORDER PROCESSING" (all caps)
+```
+
+**Rule 3: Exclude Technical Specifics**
+
+- Don't specify REST, OData, SOAP, GraphQL in API name
+- Don't specify version in API name (use versioning metadata)
+- Don't expose protocol details
+
+**Examples**:
+```
+✅ GOOD:   "Document Approval"
+❌ BAD:    "Document Approval REST API"
+❌ BAD:    "Document Approval OData v4"
+❌ BAD:    "Document Approval v2"
+```
+
+**Rule 4: Avoid Verbs and Prepositions**
+
+- API names should be nouns or noun phrases (except in rare cases)
+- Verbs belong in method/operation names
+- Prepositions should be minimized
+
+**Examples**:
+```
+✅ GOOD:   "Invoice Management"
+❌ BAD:    "Creating Invoices"
+❌ BAD:    "Manage for Invoices"
+
+✅ GOOD:   "Purchase Requisitions"
+❌ BAD:    "Retrieving Purchase Requisitions"
+```
+
+**Rule 5: Omit "SAP" Prefix**
+
+- "SAP" is context that users already know
+- Including it adds no value and increases verbosity
+- Reserve for disambiguation only
+
+**Examples**:
+```
+✅ GOOD:   "Human Capital Management Employees"
+❌ BAD:    "SAP Human Capital Management Employees"
+
+✅ GOOD:   "Travel Management"
+❌ BAD:    "SAP Travel Management"
+```
+
+---
+
+## Word Combination Conventions
+
+### 1. camelCase (Lower Camel Case)
+
+**Definition**: First word lowercase, subsequent words capitalized, no separators.
+
+**Usage**:
+- REST/OData query parameters
+- REST/OData request/response fields
+- Java methods, parameters, variables
+- JavaScript functions, variables, object properties
+- .NET and C++ variable names (some cases)
+
+**Pattern**: `firstWordLowerRestWordsCapitalized`
+
+**Examples**:
+```
+✅ customerAddress
+✅ getOrderStatus
+✅ isActiveUser
+✅ totalAmountDue
+✅ createPurchaseOrder
+
+❌ customeraddress (no capitalization)
+❌ GetOrderStatus (wrong language - PascalCase)
+❌ get_order_status (wrong convention - snake_case)
+```
+
+**Word Boundaries**:
+- Start new word with capital letter
+- No spaces, hyphens, or underscores
+- Numbers typically stay attached: `oauth2Token` not `oAuth2Token`
+- Acronyms handled specially (see [Acronym Guidelines](#acronym-guidelines))
+
+### 2. PascalCase (Upper Camel Case)
+
+**Definition**: First word capitalized, subsequent words capitalized, no separators.
+
+**Usage**:
+- REST/OData resource names (preferred in many contexts)
+- Java class names, interface names, enum names
+- JavaScript class names, constructors
+- .NET class names, namespace segments, method names
+- C/C++ class names, enum names
+
+**Pattern**: `FirstWordCapitalizedRestWordsCapitalized`
+
+**Examples**:
+```
+✅ CustomerAddress
+✅ GetOrderStatus
+✅ IsActiveUser
+✅ TotalAmountDue
+✅ CreatePurchaseOrder
+
+❌ customeraddress (no capitalization)
+❌ customerAddress (wrong style - camelCase)
+❌ CUSTOMER_ADDRESS (wrong convention - UPPER_CASE)
+```
+
+### 3. kebab-case (Hyphenated Case)
+
+**Definition**: All lowercase words separated by hyphens.
+
+**Usage**:
+- REST/OData URI paths (alternative to camelCase)
+- REST query parameter names (when not camelCase)
+- HTTP header names (some conventions)
+- Command-line options
+- URLs and file paths
+
+**Pattern**: `first-word-lowercase-rest-words-lowercase-separated-by-hyphens`
+
+**Examples**:
+```
+✅ customer-address
+✅ order-status
+✅ is-active-user
+✅ total-amount-due
+✅ /orders/{order-id}/items/{item-id}
+
+❌ Customer-Address (wrong capitalization)
+❌ customer_address (wrong separator - underscore)
+❌ customerAddress (wrong style - camelCase)
+```
+
+### 4. snake_case (Underscore Case)
+
+**Definition**: All lowercase words separated by underscores.
+
+**Usage**:
+- C/C++ function names, variable names
+- Python function names, variable names (less common in SAP APIs)
+- Database column names (typically)
+- Constants combined with uppercase (see [Constants](#constants))
+
+**Pattern**: `first_word_lowercase_rest_words_lowercase_separated_by_underscores`
+
+**Examples**:
+```
+✅ customer_address
+✅ get_order_status
+✅ is_active_user
+✅ total_amount_due
+
+❌ CustomerAddress (wrong convention - PascalCase)
+❌ customer-address (wrong separator - hyphen)
+❌ customerAddress (wrong style - camelCase)
+```
+
+### 5. UPPER_CASE (Constant Case)
+
+**Definition**: All uppercase words separated by underscores.
+
+**Usage**:
+- Constants (any language)
+- Macros and preprocessor directives
+- Enum values
+- Static final fields
+
+**Pattern**: `FIRST_WORD_UPPERCASE_REST_WORDS_UPPERCASE_SEPARATED_BY_UNDERSCORES`
+
+**Examples**:
+```
+✅ MAX_LENGTH
+✅ DEFAULT_TIMEOUT
+✅ API_VERSION
+✅ HTTP_STATUS_OK
+
+❌ MaxLength (wrong convention - PascalCase)
+❌ max_length (wrong case - not uppercase)
+❌ MAX-LENGTH (wrong separator - hyphen)
+```
+
+---
+
+## Acronym Guidelines
+
+### When to Use Acronyms
+
+**Use acronyms when**:
+- Widely recognized in industry: `HTTP`, `REST`, `OData`, `OAuth`, `JSON`
+- Shorter and clearer than full form: `ID` (vs. identifier)
+- Standard SAP terminology: `SAP`, `ERP`, `HCM`, `S/4HANA`
+- Product/system names: `HANA`, `Ariba`, `Concur`
+
+**Avoid acronyms when**:
+- Rarely used or highly specialized
+- Abbreviation is longer than full word: `auth` (not standard abbreviation)
+- Creates ambiguity: `AP` (could mean many things)
+- Not commonly used in documentation
+- Would make name less readable
+
+### Acronym Capitalization Rules
+
+#### 2-3 Letter Acronyms in camelCase
+
+**Rule**: Treat as single word
+- First word camelCase: lowercase acronym
+- Subsequent words camelCase: uppercase acronym (sometimes)
+
+**Examples**:
+```
+✅ httpStatusCode (HTTP is first word, lowercase h)
+✅ getHttpResponse (HTTP is not first word, stays HTTP or httpResponse depending on style)
+✅ jsonSchema (JSON is first word, lowercase j)
+✅ parseJsonData (JSON not first word)
+
+❌ HTTPStatusCode (all uppercase - wrong for camelCase)
+❌ httpstatusCode (lowercase status - consistency issue)
+```
+
+**Best Practice**: For clarity with acronyms, prefer:
+- `httpStatusCode` not `HTTPStatusCode`
+- `jsonParser` not `JSONParser` or `jsonparser`
+
+#### 4+ Letter Acronyms in camelCase
+
+**Rule**: Treat as regular word, capitalize normally
+- First word: lowercase
+- Subsequent words: capitalize first letter
+
+**Examples**:
+```
+✅ oauthToken
+✅ getOauthToken
+✅ odata4Service
+✅ parseOdataResponse
+
+❌ OAUTHToken (all uppercase - hard to read)
+❌ oauthtoken (no capitalization on subsequent word)
+```
+
+#### Acronyms in PascalCase
+
+**Rule**: Capitalize all letters of acronym when starting word
+- If acronym is entire name: all caps
+- If acronym starts compound word: capitalize only first letter, rest lowercase
+
+**Examples**:
+```
+✅ HTTPHandler (acronym at start of PascalCase)
+✅ JsonParser (four+ letters - first letter capital only)
+✅ OAuthToken (four+ letters - but commonly seen as OAuth)
+✅ RestClient (REST as first part)
+
+❌ HttpHandler (HTTP should be uppercase when first)
+❌ JSONParser (all caps looks wrong in PascalCase)
+```
+
+#### Acronyms at End of Name
+
+**Rule**: Always capitalize fully
+
+**Examples**:
+```
+✅ customerID (ID not Id)
+✅ processingXML (XML not Xml)
+✅ jsonToXML (XML not Xml)
+✅ parseJSON (JSON not Json)
+
+❌ customerId (wrong casing of acronym)
+❌ processingXml (wrong casing)
+```
+
+#### Special Cases
+
+**Known Pattern: ID**
+
+Special handling for "ID" (identifier):
+```
+✅ customerID (in camelCase context)
+✅ getByID
+✅ recordID
+✅ setID
+
+Note: Some style guides use "Id" in PascalCase, but "ID" is more common in SAP
+```
+
+**Known Pattern: HTTP/HTTPS**
+
+```
+✅ httpRequest
+✅ httpsConnection
+✅ getHttpStatus (or getHttpStatus)
+
+NOT: httpRequest (though acceptable), HTTPSConnection
+```
+
+---
+
+## REST and OData Naming
+
+### Resource Naming
+
+**Rule 1: Use Plural Forms for Collections**
+
+- Collections of items: plural noun
+- Single items/operations: singular noun
+- Consistency throughout API
+
+**Examples**:
+```
+✅ /orders (collection of orders)
+✅ /orders/{orderId} (specific order)
+✅ /orders/{orderId}/items (collection of items in order)
+✅ /orders/{orderId}/items/{itemId} (specific item)
+
+❌ /order (should be plural for collection)
+❌ /orders/{orderId}/item (should be plural for collection)
+```
+
+**Rule 2: Use Correct Grammatical Form**
+
+- Nouns should be concrete: `customer`, `product`, `invoice`
+- Avoid gerunds (verb forms): `creating` (not preferred)
+- Avoid verbs entirely: HTTP methods provide the verb
+
+**Examples**:
+```
+✅ /suppliers (noun)
+✅ /purchase-orders (noun)
+✅ /inventory (noun, singular for mass noun)
+
+❌ /get-suppliers (verb + noun - verb should be HTTP method)
+❌ /creating-orders (verb form not appropriate)
+```
+
+**Rule 3: Use American English Spelling**
+
+- Consistent with SAP documentation standards
+- Examples: `color` not `colour`, `organization` not `organisation`
+
+**Examples**:
+```
+✅ /organizations
+✅ /capitalExpenditures
+✅ /licenses
+
+❌ /organisations
+❌ /capitalExpenditures (British: expenditures)
+❌ /licences (British)
+```
+
+**Rule 4: Avoid Technical Jargon in Resource Names**
+
+- Focus on business entities and concepts
+- Hide implementation from API consumers
+
+**Examples**:
+```
+✅ /employees (business entity)
+✅ /payroll (business concept)
+
+❌ /employee-records (too specific to implementation)
+❌ /payroll-database (reveals database concept)
+❌ /emp-pay (too abbreviated)
+```
+
+### Parameter Naming
+
+**Rule 1: Use camelCase for Query and Body Parameters**
+
+- Consistency with most API conventions
+- Readability in JSON/code context
+
+**Examples**:
+```
+✅ GET /orders?customerId=123&orderStatus=PENDING
+✅ {"firstName": "John", "lastName": "Doe"}
+✅ /employees?includeTerminated=false
+
+❌ GET /orders?customer_id=123 (snake_case)
+❌ {"first-name": "John"} (kebab-case)
+```
+
+**Rule 2: Use Descriptive Parameter Names**
+
+- Full words better than abbreviations
+- Context in parameter name
+
+**Examples**:
+```
+✅ customerId (clear - refers to customer)
+✅ createdStartDate (clear - start of date range)
+✅ includeInactiveRecords
+
+❌ cId (abbreviation not clear)
+❌ startDt (abbreviation unclear)
+❌ incInact (abbreviated - hard to read)
+```
+
+**Rule 3: Common Parameter Naming Patterns**
+
+| Parameter Type | Naming Pattern | Examples |
+|---|---|---|
+| ID/Identifier | `{entityName}Id` | `customerId`, `invoiceId`, `supplierId` |
+| Filter | `{fieldName}` or `filter{FieldName}` | `status`, `orderStatus`, `filterByStatus` |
+| Sorting | `sort`, `sortBy`, `orderBy` | `sortBy=dateCreated`, `orderBy=name` |
+| Pagination | `pageSize`, `pageNumber`, `offset`, `limit` | `pageSize=50`, `offset=100`, `limit=25` |
+| Boolean flags | `is{Condition}`, `include{Item}` | `isActive`, `includeArchived`, `includePrices` |
+| Dates | `{action}{Noun}Date` | `createdDate`, `startDate`, `endDate` |
+| Range | `{field}{StartEnd}` | `priceStart`, `priceEnd`, `dateFrom`, `dateTo` |
+| Search | `search`, `query`, `keyword` | `search=john`, `query=invoice` |
+
+### URI Structure
+
+**Rule 1: Use Forward Slashes for Hierarchy**
+
+- Clear parent-child relationships
+- Reflect data model structure
+
+**Examples**:
+```
+✅ /companies/{companyId}/departments/{deptId}/employees/{empId}
+✅ /orders/{orderId}/items/{itemId}
+✅ /projects/{projectId}/tasks/{taskId}/subtasks
+
+❌ /companies/departments/employees (no IDs, ambiguous)
+❌ /employee/{empId}/order/{orderId} (illogical relationship)
+```
+
+**Rule 2: Use Path Parameters for Resource Identification**
+
+- IDs and specific resource selection in path
+- Filtering and options in query parameters
+
+**Examples**:
+```
+✅ /orders/{orderId}/items (path for hierarchy)
+✅ /orders?customerId=123&status=PENDING (query for filtering)
+✅ DELETE /orders/{orderId} (path for specific resource)
+
+❌ /orders?id=123 (ID should be in path for REST)
+❌ /orders/{status}/{date} (filtering should use query params)
+```
+
+**Rule 3: Keep URIs Readable and Concise**
+
+- Logical, predictable structure
+- Easy to remember and construct
+- Not excessively deep (3-4 levels typically good)
+
+**Examples**:
+```
+✅ /products/{id}/reviews
+✅ /customers/{id}/orders/{orderId}/items
+
+❌ /api/v1/resources/products/by-id/{id}/related/reviews (too verbose)
+❌ /p/{id}/r (too abbreviated)
+```
+
+**Rule 4: Avoid Verbs in URIs (Use HTTP Methods Instead)**
+
+- Verbs belong in HTTP methods
+- Nouns belong in URIs
+
+**Examples**:
+```
+✅ POST /orders (create order)
+✅ PUT /orders/{id} (update order)
+✅ DELETE /orders/{id} (delete order)
+✅ GET /orders (list orders)
+
+❌ POST /createOrder (verb in URI)
+❌ GET /listOrders (verb in URI)
+❌ DELETE /removeOrder/{id} (verb in URI)
+```
+
+### HTTP Method Usage
+
+**Standard HTTP Methods and When to Use**:
+
+| Method | Purpose | Idempotent | Cacheable | Resource |
+|--------|---------|-----------|-----------|----------|
+| `GET` | Retrieve resource | Yes | Yes | Safe read |
+| `POST` | Create new resource | No | No | Collection |
+| `PUT` | Replace entire resource | Yes | No | Specific item |
+| `PATCH` | Partial update | No (usually) | No | Specific item |
+| `DELETE` | Remove resource | Yes | No | Specific item |
+| `HEAD` | Like GET but no body | Yes | Yes | Specific item |
+| `OPTIONS` | Describe communication options | Yes | No | Any |
+
+**Examples**:
+```
+✅ GET /orders (retrieve list)
+✅ POST /orders (create new order)
+✅ GET /orders/{id} (retrieve specific order)
+✅ PUT /orders/{id} (replace entire order)
+✅ PATCH /orders/{id} (partial update)
+✅ DELETE /orders/{id} (delete order)
+
+❌ GET /createOrder (use POST instead)
+❌ POST /orders/{id} (use PUT or PATCH for update)
+❌ GET /deleteOrder/{id} (use DELETE instead)
+```
+
+### camelCase Rules in REST APIs
+
+**When to Use camelCase in REST**:
+- Query parameters: `?customerId=123&orderStatus=PENDING`
+- JSON request/response bodies
+- Field names in payloads
+
+**Examples**:
+```
+✅ GET /orders?customerId=123
+✅ {
+     "customerId": 123,
+     "orderStatus": "PENDING",
+     "totalAmount": 500.00,
+     "lineItems": []
+   }
+
+❌ GET /orders?customer_id=123 (snake_case - not camelCase)
+❌ {
+     "customer-id": 123 (kebab-case - not camelCase)
+   }
+```
+
+**When camelCase May Not Apply in URIs**:
+- Some organizations prefer kebab-case for URIs
+- Be consistent within your organization
+- Parameter names in query strings: use camelCase (most common)
+
+---
+
+## Native Library Naming
+
+### Java APIs
+
+#### Classes and Interfaces
+
+**Interfaces** (Java-specific):
+- Use descriptive noun-based names in UpperCamelCase
+- Do NOT use "I" prefix (discouraged in Java style guides)
+- Examples: `Comparable`, `Serializable`, `DataProvider`, `EventListener`
+- If disambiguation is needed, use descriptive suffixes: `DataProviderInterface` (rare)
+
+**Abstract Classes**:
+- Start with "Abstract": `AbstractProcessor`, `AbstractFactory`
+- Use descriptive noun: `AbstractConnectionPool`
+
+**Regular Classes**:
+- UpperCamelCase: `CustomerOrder`, `PaymentProcessor`
+- Noun phrase or single noun
+
+**Exceptions**:
+- End with "Exception": `InvalidOrderException`, `PaymentProcessingException`
+- Extend appropriate exception base class
+
+**Examples**:
+```
+✅ public class CustomerOrder { }
+✅ public interface IProperty { }
+✅ public abstract class AbstractProcessor { }
+✅ public class InvalidOrderException extends Exception { }
+
+❌ public class Customer_Order { } (snake_case)
+❌ public interface PropertyInterface { } (redundant)
+❌ public class customerOrder { } (lowerCamelCase for class)
+```
+
+#### Methods
+
+**Naming Convention**: lowerCamelCase, verb/verb phrase
+
+**Getters**: `get` + property name
+**Setters**: `set` + property name
+**Boolean queries**: `is` + condition, `has` + item, `can` + action
+
+**Examples**:
+```
+✅ public String getCustomerName() { }
+✅ public void setCustomerName(String name) { }
+✅ public boolean isActive() { }
+✅ public boolean hasChildren() { }
+✅ public boolean canDelete() { }
+✅ public List getActiveOrders() { }
+✅ public void processPayment(Payment payment) { }
+
+❌ public String GetCustomerName() { } (PascalCase for method)
+❌ public boolean active() { } (no is/has prefix)
+❌ public void get_customer_name() { } (snake_case)
+❌ public String getCustomer_Name() { } (mixed conventions)
+```
+
+#### Parameters
+
+**Naming Convention**: lowerCamelCase, noun/noun phrase
+
+**Rule**: Descriptive names even if short variable scope
+
+**Examples**:
+```
+✅ public void processOrder(Order order, Customer customer, Date dueDate) { }
+✅ public String concatenate(String first, String second) { }
+✅ public boolean validate(PaymentRequest request, AccountInfo account) { }
+
+❌ public void processOrder(Order o, Customer c, Date d) { } (single letters)
+❌ public String concatenate(String s1, String s2) { } (generic)
+```
+
+#### Constants
+
+**Naming Convention**: UPPER_CASE with underscores
+
+**Rule**: All caps, underscores between words
+
+**Examples**:
+```
+✅ public static final int MAX_BATCH_SIZE = 100;
+✅ public static final String DEFAULT_ENCODING = "UTF-8";
+✅ public static final long TIMEOUT_MILLISECONDS = 5000L;
+
+❌ public static final int maxBatchSize = 100; (lowerCamelCase)
+❌ public static final String default-encoding = "UTF-8"; (kebab-case)
+```
+
+#### Java Packages
+
+**Naming Convention**: Lowercase, dot-separated, reversed domain format
+
+**Rule**: `com.{company}.{product}.{module}`
+
+**Examples**:
+```
+✅ com.sap.portal.directory
+✅ com.sap.btp.environment
+✅ com.sap.hana.database
+✅ org.springframework.framework (third-party example)
+
+❌ Com.SAP.Portal.Directory (wrong case)
+❌ com.sap.Portal.Directory (mixed case)
+❌ SAP.Portal.Directory (no reverse domain)
+```
+
+### JavaScript APIs
+
+#### Classes and Constructors
+
+**Naming Convention**: UpperCamelCase
+
+**Examples**:
+```
+✅ class CustomerOrder { }
+✅ class PaymentProcessor { }
+✅ function DataProvider() { } (constructor function)
+
+❌ class customerOrder { } (lowerCamelCase)
+❌ class Customer_Order { } (snake_case)
+```
+
+#### Functions and Methods
+
+**Naming Convention**: lowerCamelCase, verb/verb phrase
+
+**Getters**: `get` + property name or direct property access
+**Boolean queries**: `is` + condition, `has` + item, `can` + action
+
+**Examples**:
+```
+✅ function processOrder(order) { }
+✅ function getCustomerName() { }
+✅ function isActive() { }
+✅ function hasChildren() { }
+✅ const validatePayment = (payment) => { }
+
+❌ function ProcessOrder(order) { } (PascalCase)
+❌ function process_order(order) { } (snake_case)
+```
+
+#### Variables and Properties
+
+**Naming Convention**: lowerCamelCase
+
+**Examples**:
+```
+✅ const customerName = "John";
+✅ let totalAmount = 0;
+✅ this.isProcessing = false;
+✅ const defaultTimeout = 5000;
+
+❌ const customer_name = "John"; (snake_case)
+❌ const CUSTOMER_NAME = "John"; (UPPER_CASE)
+```
+
+#### Constants
+
+**Naming Convention**: UPPER_CASE with underscores (or lowerCamelCase if scoped to module)
+
+**Examples**:
+```
+✅ const MAX_BATCH_SIZE = 100;
+✅ const DEFAULT_ENCODING = "UTF-8";
+✅ const TIMEOUT_MILLISECONDS = 5000;
+
+❌ const maxBatchSize = 100; (for module-level constants)
+```
+
+#### JavaScript Namespaces
+
+**Naming Convention**: Nested objects or modules following package conventions
+
+**Examples**:
+```
+✅ sap.portal.directory
+✅ sap.hana.database
+✅ sap.btp.cf.deploy
+
+✅ // Using ES6 modules
+   export const portalDirectory = { }
+   export const hanaDatabase = { }
+
+❌ SAP.Portal.Directory (all caps)
+❌ sap_portal_directory (snake_case)
+```
+
+### .NET APIs
+
+#### Classes and Interfaces
+
+**Interfaces**:
+- Start with capital "I": `IProperty`, `IResource`, `IIterator`
+- Use noun phrases: `IDataProvider`, `IEventListener`
+- UpperCamelCase throughout
+
+**Abstract Classes**:
+- Start with "Abstract": `AbstractProcessor`, `AbstractFactory`
+- Use descriptive noun
+
+**Classes**:
+- UpperCamelCase: `CustomerOrder`, `PaymentProcessor`
+- Noun or noun phrase
+
+**Exceptions**:
+- End with "Exception": `InvalidOrderException`, `PaymentProcessingException`
+
+**Examples**:
+```
+✅ public class CustomerOrder { }
+✅ public interface IProperty { }
+✅ public abstract class AbstractProcessor { }
+✅ public class InvalidOrderException : Exception { }
+
+❌ public class Customer_Order { } (snake_case)
+❌ public interface Property { } (no I prefix)
+```
+
+#### Methods and Properties
+
+**Naming Convention**: UpperCamelCase (verb/verb phrase)
+
+**Rule**: Different from Java - use UpperCamelCase even for methods
+
+**Examples**:
+```
+✅ public string GetCustomerName() { }
+✅ public void SetCustomerName(string name) { }
+✅ public bool IsActive { get; set; }
+✅ public List GetActiveOrders() { }
+✅ public void ProcessPayment(Payment payment) { }
+
+❌ public string getCustomerName() { } (lowerCamelCase in Java style)
+❌ public bool isActive { } (property should be UpperCamelCase)
+```
+
+#### Properties (C#)
+
+**Naming Convention**: UpperCamelCase, noun/noun phrase
+
+**Examples**:
+```
+✅ public string CustomerName { get; set; }
+✅ public bool IsActive { get; private set; }
+✅ public int OrderCount { get; }
+✅ public DateTime CreatedDate { get; set; }
+
+❌ public string customerName { } (lowerCamelCase)
+❌ public bool is_active { } (snake_case)
+```
+
+#### Parameters
+
+**Naming Convention**: lowerCamelCase
+
+**Examples**:
+```
+✅ public void ProcessOrder(Order order, Customer customer, DateTime dueDate) { }
+✅ public string Concatenate(string first, string second) { }
+
+❌ public void ProcessOrder(Order Order, Customer Customer) { }
+❌ public void ProcessOrder(Order o, Customer c) { }
+```
+
+#### Constants
+
+**Naming Convention**: UPPER_CASE with underscores or UpperCamelCase (often UpperCamelCase in .NET)
+
+**Examples**:
+```
+✅ public const int MaxBatchSize = 100;
+✅ public const string DefaultEncoding = "UTF-8";
+✅ public const int DEFAULT_TIMEOUT_MILLISECONDS = 5000;
+
+❌ public const int max_batch_size = 100;
+❌ public const string defaultEncoding = "UTF-8"; (lowerCamelCase for constants is less common)
+```
+
+#### .NET Namespaces
+
+**Naming Convention**: UpperCamelCase, dot-separated
+
+**Rule**: Reflects company/organization and logical grouping
+
+**Examples**:
+```
+✅ Sap.Data.Hana
+✅ Sap.Portal.Directory
+✅ Sap.BusinessTechnology.Platform
+✅ Microsoft.AspNetCore.Mvc
+
+❌ sap.data.hana (lowercase)
+❌ Sap_Data_Hana (underscores)
+❌ SAP.DATA.HANA (all caps)
+```
+
+### C/C++ APIs
+
+#### Functions
+
+**Naming Convention**: lowercase_with_underscores
+
+**Examples**:
+```
+✅ void process_order(order_t* order);
+✅ char* get_customer_name(customer_t* customer);
+✅ bool validate_payment(payment_t* payment);
+✅ struct list* create_order_list();
+
+❌ void ProcessOrder(order_t* order); (PascalCase)
+❌ void processOrder(order_t* order); (camelCase)
+```
+
+#### Macros
+
+**Naming Convention**: UPPER_CASE with underscores
+
+**Examples**:
+```
+✅ #define MAX_BUFFER_SIZE 1024
+✅ #define DEFAULT_TIMEOUT_MS 5000
+✅ #define SAP_ORDER_VERSION "1.0"
+
+❌ #define maxBufferSize 1024 (camelCase)
+❌ #define max-buffer-size 1024 (kebab-case)
+```
+
+#### Type Definitions (typedef)
+
+**Naming Convention**: lowercase_with_underscores, often with `_t` suffix
+
+**Examples**:
+```
+✅ typedef struct { ... } customer_t;
+✅ typedef int order_id_t;
+✅ typedef enum { ... } payment_status_t;
+
+❌ typedef struct { ... } Customer;
+❌ typedef struct { ... } CUSTOMER;
+```
+
+#### Enums
+
+**Values**: UPPER_CASE with underscores
+
+**Examples**:
+```
+✅ enum payment_status {
+     PAYMENT_STATUS_PENDING,
+     PAYMENT_STATUS_APPROVED,
+     PAYMENT_STATUS_REJECTED
+   };
+
+❌ enum payment_status {
+     Pending,
+     Approved,
+     Rejected
+   };
+```
+
+#### Variables
+
+**Naming Convention**: lowercase_with_underscores
+
+**Examples**:
+```
+✅ int customer_count = 0;
+✅ char* customer_name;
+✅ bool is_active = true;
+✅ size_t buffer_size = 1024;
+
+❌ int customerCount = 0; (camelCase)
+❌ char* CustomerName; (PascalCase)
+```
+
+#### Constants
+
+**Naming Convention**: UPPER_CASE with underscores
+
+**Examples**:
+```
+✅ #define DEFAULT_BUFFER_SIZE 1024
+✅ const int MAX_CONNECTIONS = 100;
+✅ static const char* SAP_VERSION = "1.0";
+
+❌ const int maxConnections = 100; (camelCase)
+❌ #define max_buffer_size 1024 (lowercase - not constant)
+```
+
+---
+
+## Common Mistakes to Avoid
+
+### Naming Mistakes
+
+#### 1. Inconsistent Casing
+
+**Problem**: Using different casing conventions for similar elements.
+
+```
+❌ BAD:
+{
+  "customerName": "John",
+  "customer_age": 30,
+  "CustomerStatus": "ACTIVE"
+}
+
+✅ GOOD:
+{
+  "customerName": "John",
+  "customerAge": 30,
+  "customerStatus": "ACTIVE"
+}
+```
+
+**Why**: Inconsistency confuses developers, makes code harder to remember, increases errors.
+
+**How to Fix**: Choose one convention and apply consistently throughout API.
+
+---
+
+#### 2. Abbreviations Without Clear Meaning
+
+**Problem**: Using abbreviations that are unclear or non-standard.
+
+```
+❌ BAD:
+GET /emps/{empId}/depts/{deptId}
+{
+  "eaddr": "john@company.com",
+  "sal": 50000,
+  "yrHired": 2020
+}
+
+✅ GOOD:
+GET /employees/{employeeId}/departments/{departmentId}
+{
+  "emailAddress": "john@company.com",
+  "salary": 50000,
+  "yearHired": 2020
+}
+```
+
+**Why**: Abbreviations require documentation and memory burden.
+
+**How to Fix**: Use full words unless abbreviation is universally known (ID, HTTP, REST).
+
+---
+
+#### 3. Single-Letter Variable Names
+
+**Problem**: Using single letters for variables, parameters, or endpoints.
+
+```
+❌ BAD:
+public Order p(Customer c, Item i) {
+  int q = i.getQty();
+  return new Order(c, i, q);
+}
+
+GET /o?c=123&s=PENDING
+
+✅ GOOD:
+public Order processOrder(Customer customer, Item item) {
+  int quantity = item.getQuantity();
+  return new Order(customer, item, quantity);
+}
+
+GET /orders?customerId=123&status=PENDING
+```
+
+**Why**: Single letters provide no context and make code unmaintainable.
+
+**How to Fix**: Use full descriptive names even for loop variables in public APIs.
+
+---
+
+#### 4. Non-English or Misspelled Words
+
+**Problem**: Using non-English or incorrectly spelled words.
+
+```
+❌ BAD:
+{
+  "custmer": "John",         // misspelled "customer"
+  "adress": "123 Main St",   // misspelled "address"
+  "telefone": "555-1234"     // non-English "telephone"
+}
+
+✅ GOOD:
+{
+  "customer": "John",
+  "address": "123 Main St",
+  "telephone": "555-1234"
+}
+```
+
+**Why**: Misspellings create confusion and inconsistency.
+
+**How to Fix**: Use American English spelling and standard dictionaries. Spell-check before publishing.
+
+---
+
+#### 5. Including "API" or "Service" in Name
+
+**Problem**: Redundantly including "API", "Service", "System", etc. in API names.
+
+```
+❌ BAD:
+- "Customer Orders API"
+- "Invoice Management Service"
+- "Payment Processing System APIs"
+
+✅ GOOD:
+- "Customer Orders"
+- "Invoice Management"
+- "Payment Processing"
+```
+
+**Why**: These terms are implied by context. Adding them increases verbosity without adding value.
+
+**How to Fix**: Remove technical terms. Use business entity or concept names.
+
+---
+
+#### 6. Including "SAP" in Business API Names
+
+**Problem**: Prefixing API names with "SAP" when context is already clear.
+
+```
+❌ BAD:
+- "SAP Human Capital Management"
+- "SAP Finance Reporting"
+- "SAP Supply Chain"
+
+✅ GOOD:
+- "Human Capital Management"
+- "Finance Reporting"
+- "Supply Chain"
+```
+
+**Why**: "SAP" is already known context. Reduces clarity.
+
+**How to Fix**: Use only when necessary for disambiguation.
+
+---
+
+#### 7. Mixing Naming Conventions
+
+**Problem**: Mixing camelCase, snake_case, and PascalCase in same element.
+
+```
+❌ BAD:
+GET /order_items?customer_ID=123&OrderStatus=PENDING
+{
+  "order_id": "123",
+  "itemCount": 5,
+  "total-amount": 500
+}
+
+✅ GOOD:
+GET /orderItems?customerId=123&orderStatus=PENDING
+{
+  "orderId": "123",
+  "itemCount": 5,
+  "totalAmount": 500
+}
+```
+
+**Why**: Mixed conventions are confusing and violate language-specific standards.
+
+**How to Fix**: Choose convention per language and apply consistently.
+
+---
+
+#### 8. Verbs in Resource Names
+
+**Problem**: Using verbs or verb phrases for resource names instead of relying on HTTP methods.
+
+```
+❌ BAD:
+GET /getOrders
+POST /createOrder
+PUT /updateOrder/{id}
+DELETE /removeOrder/{id}
+
+✅ GOOD:
+GET /orders
+POST /orders
+PUT /orders/{id}
+DELETE /orders/{id}
+```
+
+**Why**: HTTP methods provide verbs. Duplicating creates redundancy.
+
+**How to Fix**: Use nouns for resources, HTTP methods for actions.
+
+---
+
+#### 9. Acronym Casing Issues
+
+**Problem**: Inconsistent capitalization of acronyms.
+
+```
+❌ BAD:
+{
+  "HTTPStatus": 200,
+  "JsonFormat": "compact",
+  "oAuthToken": "abc123",
+  "restfulAPI": "v2"
+}
+
+✅ GOOD:
+{
+  "httpStatus": 200,
+  "jsonFormat": "compact",
+  "oauthToken": "abc123",
+  "restfulAPI": "v2" (or "restfulApi" depending on style guide)
+}
+```
+
+**Why**: Inconsistent acronym casing looks unprofessional and confuses developers.
+
+**How to Fix**: Apply acronym rules consistently (see [Acronym Guidelines](#acronym-guidelines)).
+
+---
+
+#### 10. Past Tense for Present Actions
+
+**Problem**: Using past tense for methods/operations that perform present actions.
+
+```
+❌ BAD:
+public void orderCreated(Order order) { }
+public void getOrderProcessed() { }
+public void validatePaymentSubmitted() { }
+
+✅ GOOD:
+public void createOrder(Order order) { }
+public void getProcessedOrder() { }
+public void validatePaymentSubmission() { }
+```
+
+**Why**: APIs describe what they do now, not what was done.
+
+**How to Fix**: Use present tense for method names.
+
+---
+
+#### 11. Unclear Boolean Naming
+
+**Problem**: Using unclear or inverted boolean names.
+
+```
+❌ BAD:
+GET /orders?notCancelled=true
+public boolean disabled;
+public boolean noErrors;
+
+✅ GOOD:
+GET /orders?status=ACTIVE
+public boolean isActive;
+public boolean hasErrors;
+```
+
+**Why**: Boolean names should be clear and positive. Double negatives are confusing.
+
+**How to Fix**: Use "is", "has", or "can" prefixes with positive conditions.
+
+---
+
+#### 12. Underscore Overuse
+
+**Problem**: Using underscores excessively or in wrong places.
+
+```
+❌ BAD:
+public void get_customer_address_by_id(long _cust_id) { }
+GET /api/v1/resources/_/orders?_sort=_date
+
+✅ GOOD:
+public void getCustomerAddressById(long customerId) { }
+GET /api/v1/orders?sort=date
+```
+
+**Why**: Excessive underscores reduce readability.
+
+**How to Fix**: Use underscores only for constants and snake_case contexts (C/C++).
+
+---
+
+### REST/OData Specific Mistakes
+
+#### 13. Inconsistent Plural/Singular
+
+**Problem**: Mixing singular and plural forms in collections.
+
+```
+❌ BAD:
+GET /orders/{id}/item
+GET /products
+GET /supplier/{id}/contact
+
+✅ GOOD:
+GET /orders/{id}/items
+GET /products
+GET /suppliers/{id}/contacts
+```
+
+**Why**: Inconsistency breaks URI patterns and confuses developers.
+
+**How to Fix**: Always use plural for collections, singular for individual items.
+
+---
+
+#### 14. Query Parameters in Path
+
+**Problem**: Putting filtering/query logic in path instead of query parameters.
+
+```
+❌ BAD:
+GET /orders/PENDING/2024-01-01
+GET /employees/ACTIVE/NEW_YORK
+
+✅ GOOD:
+GET /orders?status=PENDING&createdDate=2024-01-01
+GET /employees?status=ACTIVE&location=NEW_YORK
+```
+
+**Why**: Query parameters are semantic home for filtering/sorting.
+
+**How to Fix**: Use path for resource identification, query parameters for filtering.
+
+---
+
+#### 15. Inconsistent ID Naming
+
+**Problem**: Using different ID names for same entity.
+
+```
+❌ BAD:
+GET /orders/{orderId}
+GET /orders/{orderId}/items/{id}
+GET /orders/{order_id}/customer/{customerId}
+
+✅ GOOD:
+GET /orders/{orderId}
+GET /orders/{orderId}/items/{itemId}
+GET /orders/{orderId}/customer/{customerId}
+```
+
+**Why**: Inconsistent ID naming breaks predictability.
+
+**How to Fix**: Use `{entityName}Id` pattern consistently.
+
+---
+
+### Native Library Specific Mistakes
+
+#### 16. Method Names Without Verbs
+
+**Problem**: Methods named as nouns instead of verb phrases.
+
+```
+❌ BAD (Java):
+public void order(Customer customer) { }
+public String address() { }
+
+✅ GOOD (Java):
+public void createOrder(Customer customer) { }
+public String getAddress() { }
+```
+
+**Why**: Methods perform actions, so verb phrases are more semantic.
+
+**How to Fix**: Use verb/verb phrase for method names.
+
+---
+
+#### 17. Inconsistent Getter/Setter Naming
+
+**Problem**: Using inconsistent patterns for accessors.
+
+```
+❌ BAD (Java):
+public String getName() { }
+public void setName(String value) { }
+public void age(int years) { }         // not a getter
+public int retrieveAge() { }           // inconsistent
+
+✅ GOOD (Java):
+public String getName() { }
+public void setName(String name) { }
+public int getAge() { }
+public void setAge(int age) { }
+```
+
+**Why**: Consistent accessor patterns aid discoverability and reduce learning curve.
+
+**How to Fix**: Use `get`/`set` pattern consistently for properties.
+
+---
+
+#### 18. Class Names as Verbs
+
+**Problem**: Using verb phrases for class names instead of noun phrases.
+
+```
+❌ BAD:
+public class CreateOrder { }
+public class ProcessPayment { }
+public class ValidateAddress { }
+
+✅ GOOD:
+public class OrderProcessor { }
+public class PaymentProcessor { }
+public class AddressValidator { }
+
+// Or if returning result:
+public class Order { }
+public class Payment { }
+public class Address { }
+```
+
+**Why**: Classes are entities/concepts (nouns), not actions (verbs).
+
+**How to Fix**: Use noun-based class names, potentially with descriptive suffix (-Processor, -Handler, -Factory, etc.).
+
+---
+
+#### 19. Interface Naming (Language-Specific)
+
+**C#/.NET Convention**: Use "I" prefix for interfaces.
+
+```
+✅ GOOD (.NET):
+public interface IDataProvider { }
+public interface IOrderRepository { }
+```
+
+**Java Convention**: Do NOT use "I" prefix (actively discouraged).
+
+```
+✅ GOOD (Java):
+public interface DataProvider { }
+public interface OrderRepository { }
+public interface Comparable { }
+```
+
+**C++ Convention**: Follow project style guide (no universal rule).
+- Preferred: Descriptive names or Abstract/Factory prefixes
+- Examples: `DataProvider`, `AbstractProvider`, `ProviderFactory`
+
+**Why**: Different languages have different established conventions. Java style guides (including Google Java Style Guide, Oracle conventions) discourage the "I" prefix as redundant.
+
+**How to Fix**: Apply language-specific conventions:
+- **C#/.NET**: Add "I" prefix
+- **Java**: Use descriptive names without prefix
+- **C++**: Follow project style guide
+
+---
+
+#### 20. Parameter Names That Repeat Class Name
+
+**Problem**: Using same name for parameter as containing class.
+
+```
+❌ BAD (Java):
+public class Order {
+  public void setOrder(Order order) { }
+  public Order getOrder() { }
+}
+
+✅ GOOD (Java):
+public class Order {
+  // Properties, not duplicate parameter names
+  public int id;
+  public String status;
+
+  // Methods with clear parameter names
+  public void update(Order newOrder) { }
+  public static Order fromJson(String json) { }
+}
+```
+
+**Why**: Parameter names should distinguish intent, not repeat class context.
+
+**How to Fix**: Use descriptive parameter names that clarify purpose (newOrder, updatedOrder, etc.).
+
+---
+
+## Reference Tables
+
+### Complete Naming Convention Matrix
+
+| Element | Java | JavaScript | .NET | C/C++ | REST URI | REST JSON |
+|---------|------|-----------|------|-------|----------|-----------|
+| **Classes** | `UpperCamelCase` | `UpperCamelCase` | `UpperCamelCase` | `lowercase_snake` | N/A | N/A |
+| **Interfaces** | `IUpperCamelCase` | `IUpperCamelCase` | `IUpperCamelCase` | `lowercase_snake` | N/A | N/A |
+| **Methods** | `lowerCamelCase` | `lowerCamelCase` | `UpperCamelCase` | `lowercase_snake` | N/A | N/A |
+| **Functions** | N/A | `lowerCamelCase` | N/A | `lowercase_snake` | N/A | N/A |
+| **Properties** | `lowerCamelCase` | `lowerCamelCase` | `UpperCamelCase` | `lowercase_snake` | N/A | camelCase |
+| **Variables** | `lowerCamelCase` | `lowerCamelCase` | `lowerCamelCase` | `lowercase_snake` | N/A | N/A |
+| **Parameters** | `lowerCamelCase` | `lowerCamelCase` | `lowerCamelCase` | `lowercase_snake` | camelCase | camelCase |
+| **Constants** | `UPPER_CASE` | `UPPER_CASE` | `UpperCamelCase` | `UPPER_CASE` | N/A | N/A |
+| **Enums** | `UpperCamelCase` (type), `UPPER_CASE` (values) | `UpperCamelCase` (type), `UPPER_CASE` (values) | `UpperCamelCase` (type), `UpperCamelCase` (values) | `enum` name, `UPPER_CASE` (values) | N/A | N/A |
+| **Resources** | N/A | N/A | N/A | N/A | Plural noun | N/A |
+| **Query Params** | N/A | N/A | N/A | N/A | camelCase | N/A |
+| **Packages** | `com.company.product` | `module.namespace` | `Company.Product` | `company_module` | N/A | N/A |
+
+### Common Pattern Templates
+
+#### API Naming Patterns
+
+| Pattern | Template | Example |
+|---------|----------|---------|
+| **Business Entity** | Noun phrase | "Customer Orders", "Supplier Management" |
+| **Business Process** | Noun phrase | "Invoice Approval", "Payment Processing" |
+| **Business Concept** | Noun phrase | "Budgeting", "Forecasting", "Consolidation" |
+| **Technical Layer** | Noun + type | Not recommended - avoid in names |
+
+#### URI Pattern Templates
+
+| Use Case | Pattern | Example |
+|----------|---------|---------|
+| **Collection** | `/resources` | `/orders`, `/employees` |
+| **Specific Item** | `/resources/{id}` | `/orders/{orderId}` |
+| **Sub-resource** | `/resources/{id}/subresources` | `/orders/{orderId}/items` |
+| **Sub-resource Item** | `/resources/{id}/subresources/{id}` | `/orders/{orderId}/items/{itemId}` |
+| **Query** | `/resources?param=value` | `/orders?status=PENDING` |
+| **Filter + Sort** | `/resources?filter&sort` | `/orders?customerId=123&sort=date` |
+| **Pagination** | `/resources?pageNumber&pageSize` | `/orders?pageNumber=1&pageSize=50` |
+
+#### Method Naming Pattern Templates
+
+**Java/JavaScript**:
+
+| Action | Template | Example |
+|--------|----------|---------|
+| Create | `create{Entity}` | `createOrder()`, `createInvoice()` |
+| Retrieve | `get{Entity}` | `getOrder()`, `getOrderList()` |
+| Update | `update{Entity}` | `updateOrder()`, `updateOrderStatus()` |
+| Delete | `delete{Entity}` | `deleteOrder()` |
+| Check | `is{Condition}` | `isActive()`, `isValid()` |
+| Check | `has{Property}` | `hasChildren()`, `hasError()` |
+| Find | `find{Entity}By{Property}` | `findOrderByCustomerId()` |
+| Process | `process{Entity}` | `processPayment()`, `processOrder()` |
+| Validate | `validate{Entity}` | `validateOrder()`, `validatePayment()` |
+
+**.NET/C++**:
+
+| Action | Template | Example |
+|--------|----------|---------|
+| Create | `Create{Entity}` | `CreateOrder()`, `CreateInvoice()` |
+| Retrieve | `Get{Entity}` | `GetOrder()`, `GetOrderList()` |
+| Update | `Update{Entity}` | `UpdateOrder()`, `UpdateOrderStatus()` |
+| Delete | `Delete{Entity}` | `DeleteOrder()` |
+| Process | `Process{Entity}` | `ProcessPayment()`, `ProcessOrder()` |
+
+#### Parameter Naming Pattern Templates
+
+| Concept | Pattern | Example |
+|---------|---------|---------|
+| **Identifier** | `{entity}Id` | `customerId`, `orderId`, `invoiceId` |
+| **Status/Type** | `{entity}Status` | `orderStatus`, `paymentStatus` |
+| **Boolean flag** | `is{Condition}` | `isActive`, `isArchived` |
+| **Boolean flag** | `include{Item}` | `includeDetail`, `includeTax` |
+| **Date range** | `{field}Start`, `{field}End` | `dateStart`, `dateEnd` |
+| **Date range** | `{field}From`, `{field}To` | `dateFrom`, `dateTo` |
+| **Search** | `search`, `query`, `keyword` | `search=john`, `query=invoice` |
+| **Sorting** | `sortBy`, `sort`, `order` | `sortBy=date`, `order=asc` |
+| **Pagination** | `pageNumber`, `pageSize`, `offset`, `limit` | `pageNumber=1`, `limit=50` |
+| **Filtering** | `filter{Property}` | `filterByStatus`, `filterByDate` |
+
+---
+
+## Naming Decision Trees
+
+### Choosing Casing Convention
+
+```
+┌─ What language/platform?
+│
+├─ REST/OData API URIs
+│  └─ camelCase or kebab-case?
+│     ├─ camelCase: Common in JSON APIs, matches JSON fields
+│     └─ kebab-case: Readable, human-friendly URIs
+│
+├─ REST/OData JSON Fields
+│  └─ Use: camelCase (standard)
+│
+├─ Java
+│  ├─ Classes? → UpperCamelCase
+│  ├─ Methods/Variables? → lowerCamelCase
+│  ├─ Constants? → UPPER_CASE
+│  └─ Packages? → lowercase.dot.separated
+│
+├─ JavaScript
+│  ├─ Classes? → UpperCamelCase
+│  ├─ Functions/Variables? → lowerCamelCase
+│  ├─ Constants? → UPPER_CASE
+│  └─ Modules? → lowercase.dot.separated or camelCase
+│
+├─ .NET (C#)
+│  ├─ Classes/Methods/Properties? → UpperCamelCase
+│  ├─ Private fields? → _privateFieldName or lowerCamelCase
+│  ├─ Constants? → UpperCamelCase or UPPER_CASE
+│  └─ Namespaces? → Company.Product.Module
+│
+└─ C/C++
+   ├─ Functions/Variables? → lowercase_snake_case
+   ├─ Macros/Constants? → UPPER_CASE
+   ├─ Types/Structs? → lowercase_snake_case_t (with _t suffix)
+   └─ Enums? → UPPER_CASE values
+```
+
+### Choosing Resource Naming Pattern
+
+```
+┌─ What are you naming?
+│
+├─ REST/OData Resource
+│  ├─ Collection?
+│  │  └─ Use plural noun: /orders, /employees, /suppliers
+│  │
+│  ├─ Individual item?
+│  │  └─ Use singular with ID: /orders/{orderId}
+│  │
+│  └─ Sub-resource?
+│     └─ Parent/children hierarchy: /orders/{orderId}/items
+│
+├─ Query Parameter
+│  ├─ Filtering by status?
+│  │  └─ Use field name: status, orderStatus
+│  │
+│  ├─ Filtering by ID?
+│  │  └─ Use: {entityName}Id, e.g., customerId
+│  │
+│  ├─ Pagination?
+│  │  └─ Use standard: pageNumber, pageSize, offset, limit
+│  │
+│  └─ Boolean flag?
+│     └─ Use is/include prefix: isActive, includeTax
+│
+└─ Native Library API
+   ├─ Public class?
+   │  └─ Noun/Noun phrase: OrderProcessor, PaymentHandler
+   │
+   ├─ Method?
+   │  └─ Verb/Verb phrase: processOrder(), getCustomerName()
+   │
+   ├─ Parameter?
+   │  └─ Noun/Noun phrase: customer, paymentAmount, orderDate
+   │
+   └─ Constant?
+      └─ UPPER_CASE: MAX_BATCH_SIZE, DEFAULT_TIMEOUT
+```
+
+### Choosing Between Verb Patterns
+
+```
+┌─ What action do you need?
+│
+├─ Create new entity
+│  └─ Use: create{Entity}() or POST /resources
+│
+├─ Get/Read entity
+│  └─ Use: get{Entity}() or GET /resources/{id}
+│
+├─ Update entity
+│  └─ Use: update{Entity}() or PUT/PATCH /resources/{id}
+│
+├─ Delete entity
+│  └─ Use: delete{Entity}() or DELETE /resources/{id}
+│
+├─ Process/Handle entity
+│  └─ Use: process{Entity}(), handle{Entity}()
+│
+├─ Validate entity
+│  └─ Use: validate{Entity}()
+│
+├─ Find entity by condition
+│  └─ Use: find{Entity}By{Property}()
+│
+├─ Check boolean condition
+│  ├─ Is something true?
+│  │  └─ Use: is{Condition}() - returns boolean
+│  │
+│  ├─ Does entity have something?
+│  │  └─ Use: has{Item}() - returns boolean
+│  │
+│  └─ Can we do something?
+│     └─ Use: can{Action}() - returns boolean
+│
+└─ Transform/Convert
+   └─ Use: to{Format}(), from{Format}(), parse{Type}()
+```
+
+---
+
+## Best Practices Summary
+
+### 10 Golden Rules of API Naming
+
+**1. Be Descriptive**
+- Names should be self-documenting
+- Developer should understand purpose without documentation
+- Avoid cryptic abbreviations
+
+**2. Be Consistent**
+- Use same conventions across entire API
+- Don't mix camelCase and snake_case
+- Maintain consistent terminology
+
+**3. Be Language-Appropriate**
+- Follow conventions of target language
+- Java uses camelCase for methods; .NET uses UpperCamelCase
+- REST APIs use camelCase or kebab-case for URIs
+
+**4. Use English (American)**
+- Standard spelling: "color" not "colour"
+- Consistent with international SAP documentation
+- Aids translation and localization
+
+**5. Use Nouns for Things, Verbs for Actions**
+- Entities: nouns (Customer, Order, Invoice)
+- Operations: verbs (create, update, delete, process)
+- Resources: plural nouns (/orders, /employees)
+
+**6. Avoid Technical Jargon in Business APIs**
+- Focus on business concepts
+- Hide implementation details
+- Use terms users understand
+
+**7. Don't Include Redundant Words**
+- No "API" in API names
+- No "REST" in REST API names
+- No "Object" after class names
+- No "Manager" or "Handler" unless it adds meaning
+
+**8. Use Standard Patterns**
+- Follow established conventions in your domain
+- Use pattern templates for consistency
+- Document chosen patterns
+
+**9. Review with Users**
+- Ensure names make sense to API consumers
+- Validate technical accuracy
+- Get feedback from diverse team members
+
+**10. Keep It Simple**
+- Shorter names are better (if still clear)
+- Avoid unnecessary complexity
+- Regular words over technical jargon
+
+### Checklist Before Publishing
+
+```
+Naming Conventions Pre-Publication Checklist:
+
+[ ] API Name
+    [ ] No "API" suffix
+    [ ] Proper title case capitalization
+    [ ] No technical specifics (REST, OData, v2)
+    [ ] No "SAP" prefix (unless needed for disambiguation)
+    [ ] Uses nouns, not verbs/prepositions
+
+[ ] Resource Names (REST/OData)
+    [ ] Plural forms for collections
+    [ ] Singular + ID for individual items
+    [ ] American English spelling
+    [ ] Consistent across all resources
+    [ ] No verbs in URI paths
+
+[ ] Parameter Names
+    [ ] Consistent casing (camelCase recommended)
+    [ ] Descriptive names (not abbreviated)
+    [ ] Follows pattern for type: {entity}Id, is{Condition}, etc.
+    [ ] No duplicate names across API
+
+[ ] Method/Function Names
+    [ ] Language-appropriate casing
+    [ ] Verb/verb phrase format
+    [ ] Consistent patterns: get/set, create/delete
+    [ ] Clear intent without documentation
+
+[ ] Class/Type Names
+    [ ] Noun/noun phrase format
+    [ ] Language-appropriate casing
+    [ ] Interfaces prefixed with "I" (where applicable)
+    [ ] Abstract classes marked clearly
+
+[ ] Parameter Names
+    [ ] Descriptive (no single letters in APIs)
+    [ ] Follows language conventions
+    [ ] Consistent across similar methods
+
+[ ] Constants
+    [ ] UPPER_CASE with underscores
+    [ ] Meaningful names
+    [ ] Grouped logically
+
+[ ] Acronyms
+    [ ] Only well-known acronyms used
+    [ ] Consistent capitalization
+    [ ] Follows language-specific rules
+
+[ ] Overall
+    [ ] No mixed conventions in same API
+    [ ] Consistent terminology
+    [ ] Reviewed by team/stakeholders
+    [ ] Matches official standards (SAP API Style Guide)
+```
+
+---
+
+## Quick Reference by Scenario
+
+### Scenario 1: Building a REST API
+
+**Steps**:
+1. Name API using business concept (no "API" suffix)
+2. Name resources using plural nouns
+3. Use camelCase for query parameters and JSON fields
+4. Use HTTP methods for verbs (GET, POST, PUT, DELETE)
+5. Use {entityId} pattern for path parameters
+6. Use camelCase for request/response fields
+
+**Example**:
+```
+API Name: "Purchase Orders"
+
+Resources:
+GET /purchaseOrders                    // list
+POST /purchaseOrders                   // create
+GET /purchaseOrders/{orderId}          // get one
+PUT /purchaseOrders/{orderId}          // update
+DELETE /purchaseOrders/{orderId}       // delete
+
+Query Parameters:
+GET /purchaseOrders?supplierId=123&status=PENDING&limit=50
+
+JSON Fields:
+{
+  "orderId": "PO-2024-001",
+  "supplierId": 123,
+  "orderDate": "2024-01-15",
+  "totalAmount": 5000.00,
+  "orderStatus": "PENDING"
+}
+```
+
+### Scenario 2: Writing Java API
+
+**Steps**:
+1. Classes: UpperCamelCase nouns
+2. Methods: lowerCamelCase verb phrases
+3. Parameters: lowerCamelCase nouns
+4. Constants: UPPER_CASE with underscores
+5. Packages: lowercase.dot.separated
+6. Interfaces: IUpperCamelCase
+
+**Example**:
+```java
+package com.sap.procurement.orders;
+
+public interface IOrderService {
+    Order createOrder(Customer customer, List items);
+    Order getOrder(String orderId);
+    void updateOrderStatus(String orderId, OrderStatus status);
+    void deleteOrder(String orderId);
+    boolean isOrderValid(Order order);
+}
+
+public class OrderProcessor {
+    public static final int MAX_ORDER_SIZE = 100;
+    public static final long DEFAULT_TIMEOUT_MS = 5000L;
+
+    public void processOrder(Order order, Supplier supplier) {
+        // implementation
+    }
+
+    private boolean validateOrder(Order order) {
+        // implementation
+    }
+}
+```
+
+### Scenario 3: Documenting .NET API
+
+**Steps**:
+1. Classes/Methods/Properties: UpperCamelCase
+2. Parameters: lowerCamelCase
+3. Constants: UpperCamelCase
+4. Namespaces: Company.Product.Module
+5. Interfaces: IInterfaceName
+
+**Example**:
+```csharp
+namespace Sap.Procurement.Orders
+{
+    public interface IOrderService
+    {
+        Order CreateOrder(Customer customer, List items);
+        Order GetOrder(string orderId);
+        void UpdateOrderStatus(string orderId, OrderStatus status);
+        void DeleteOrder(string orderId);
+        bool IsOrderValid(Order order);
+    }
+
+    public class OrderProcessor
+    {
+        public const int MaxOrderSize = 100;
+        public const long DefaultTimeoutMs = 5000L;
+
+        public void ProcessOrder(Order order, Supplier supplier)
+        {
+            // implementation
+        }
+
+        private bool ValidateOrder(Order order)
+        {
+            // implementation
+        }
+    }
+}
+```
+
+### Scenario 4: Writing JavaScript API
+
+**Steps**:
+1. Classes: UpperCamelCase
+2. Functions/Methods: lowerCamelCase
+3. Variables: lowerCamelCase
+4. Constants: UPPER_CASE
+5. Namespaces: module.namespace or nested objects
+
+**Example**:
+```javascript
+// sap/procurement/orders/OrderService.js
+
+class OrderService {
+    constructor() {
+        this.MAX_ORDER_SIZE = 100;
+        this.DEFAULT_TIMEOUT_MS = 5000;
+    }
+
+    createOrder(customer, items) {
+        // implementation
+    }
+
+    getOrder(orderId) {
+        // implementation
+    }
+
+    updateOrderStatus(orderId, status) {
+        // implementation
+    }
+
+    deleteOrder(orderId) {
+        // implementation
+    }
+
+    isOrderValid(order) {
+        // implementation
+    }
+}
+
+module.exports = OrderService;
+```
+
+---
+
+## Resources and References
+
+### Official Standards
+- **SAP API Style Guide**: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide)
+- **OpenAPI Specification**: [https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html)
+- **OData v4.01**: [https://www.odata.org/documentation/](https://www.odata.org/documentation/)
+- **Oracle Javadoc Guide**: [https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html)
+- **JSDoc 3**: [https://jsdoc.app/](https://jsdoc.app/)
+- **Microsoft .NET Guidelines**: [https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines)
+- **Google Java Style Guide**: [https://google.github.io/styleguide/javaguide.html](https://google.github.io/styleguide/javaguide.html)
+- **Airbnb JavaScript Style Guide**: [https://github.com/airbnb/javascript](https://github.com/airbnb/javascript)
+- **C++ Guidelines**: [https://isocpp.github.io/CppCoreGuidelines/](https://isocpp.github.io/CppCoreGuidelines/)
+
+### Related Documentation
+- **REST API Best Practices**: [https://restfulapi.net/](https://restfulapi.net/)
+- **OData Best Practices**: [https://www.odata.org/blog/](https://www.odata.org/blog/)
+- **Naming Conventions Survey**: [https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html)
+
+---
+
+**Document Version**: 1.0.0
+**Last Updated**: 2025-11-21
+**Maintained By**: SAP Skills Team
+**License**: GPL-3.0
diff --git a/references/quality-processes.md b/references/quality-processes.md
new file mode 100644
index 0000000..340f195
--- /dev/null
+++ b/references/quality-processes.md
@@ -0,0 +1,1774 @@
+# API Documentation Quality & Process Guide
+
+A comprehensive reference for developers and User Assistance (UA) teams creating and reviewing SAP API documentation.
+
+**Based on**: SAP API Style Guide v2021.01
+**Last Updated**: 2025-11-21
+
+**Attribution**: Content derived from [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide) (Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))
+
+**Changes**: Consolidated from multiple source files, reorganized for progressive disclosure, added examples and templates.
+
+**Audience**: Developers, Technical Writers, Product Managers, UA Developers
+
+---
+
+## Table of Contents
+
+1. [API Documentation Processes Overview](#api-documentation-processes-overview)
+2. [API Quality Checklist](#api-quality-checklist)
+3. [API Review Process](#api-review-process)
+4. [Guidelines for Development Teams](#guidelines-for-development-teams)
+5. [Best Practices](#best-practices)
+6. [Process Flowcharts](#process-flowcharts)
+7. [Review Checklists & Templates](#review-checklists--templates)
+8. [Common Review Findings](#common-review-findings)
+
+---
+
+## API Documentation Processes Overview
+
+### Purpose
+
+API documentation processes ensure that SAP APIs can be consumed quickly and easily. This requires:
+- **Quality documentation** that clearly explains API purpose and usage
+- **Consistent review workflows** involving developers and UA professionals
+- **Early identification** of documentation issues before APIs reach consumers
+- **Standardized approaches** across all SAP API implementations
+
+### Core Principle
+
+> "To ensure that an API can be consumed quickly and easily, it's important to have all texts checked and reviewed."
+
+### Three Key Components
+
+#### 1. **API Review Process**
+Structured workflow for reviewing all API documentation materials through developer-UA collaboration.
+
+#### 2. **API Quality Checklist**
+Verification tool to confirm documentation meets quality standards before publication.
+
+#### 3. **Development Team Guidelines**
+Best practices for integrating API review into development workflows.
+
+### Important Context
+
+**Note on Existing APIs**: Many existing APIs on SAP API Business Hub predate the API Style Guide and may not fully adhere to current standards. When creating new APIs, follow the style guide recommendations rather than using older examples as templates.
+
+---
+
+## API Quality Checklist
+
+### Overview
+
+The quality checklist helps developers and technical writers ensure API reference documentation is production-ready. Recommendation: Have different reviewers examine different sections to catch more issues.
+
+### Auto-Generated API Documentation
+
+#### 1. Creating/Editing API Specification Files
+
+**Documentation Comments**:
+- [ ] Use appropriate documentation tags for your API type
+  - REST/OData: OpenAPI/Swagger conventions
+  - Java: Javadoc tags
+  - JavaScript: JSDoc tags
+  - MS.NET: XML documentation tags
+  - C/C++: Doxygen tags
+- [ ] Include documentation comments throughout the specification
+- [ ] Place comments in correct location for your API type
+
+**Parameter Documentation**:
+- [ ] Are the descriptions for each parameter clear and precise?
+- [ ] Do descriptions accurately reflect parameter behavior?
+- [ ] Are parameter types correctly specified?
+- [ ] Are required vs. optional parameters clearly marked?
+
+**Complex Concept Examples**:
+- [ ] Use examples to illustrate complex concepts
+- [ ] Include sample code/payloads for non-obvious behavior
+- [ ] Verify examples are accurate and complete
+- [ ] Test code examples run without errors
+
+**Security & Privacy**:
+- [ ] Verify API doesn't include sensitive or internal information
+- [ ] Avoid including:
+  - Sample user IDs or credentials
+  - Server addresses or hostnames
+  - Internal payload examples
+  - Confidential data structures
+  - Personal information (emails, addresses)
+
+#### 2. Reviewing API Specification Files
+
+**Consistency Verification**:
+- [ ] Ensure descriptions of similar elements are consistent in style
+- [ ] Verify detail levels match across comparable API elements
+- [ ] Check terminology is consistent throughout
+- [ ] Confirm naming patterns follow conventions
+
+**Tag Organization**:
+- [ ] Are tags grouped logically?
+- [ ] Are tags ordered consistently across similar elements?
+- [ ] Is tag ordering aligned with style guide recommendations?
+- [ ] No redundant or conflicting tags?
+
+**UA Developer Review**:
+- [ ] Has a UA developer reviewed all API names?
+- [ ] Has a UA developer reviewed all descriptions?
+- [ ] Has feedback been documented and tracked?
+- [ ] Are revisions complete and verified?
+
+**Formatting & Completeness**:
+- [ ] Is all formatting correct and complete?
+- [ ] Are required fields populated?
+- [ ] Are optional fields appropriately used?
+- [ ] No incomplete or placeholder text remains?
+
+**Compilation & Generation**:
+- [ ] Does documentation compile completely?
+- [ ] Build process completes without errors?
+- [ ] No warnings or deprecation notices?
+- [ ] Generated output is valid and well-formed?
+
+**Link Verification**:
+- [ ] Do all links work correctly?
+- [ ] Links point to current, active resources?
+- [ ] Cross-references resolve properly?
+- [ ] No dead links or redirects?
+
+**Output Quality**:
+- [ ] Does output look as expected?
+- [ ] Does layout render correctly?
+- [ ] Are all images/diagrams displaying?
+- [ ] Is the output accessible on all target platforms?
+
+---
+
+### Manually Written API Documentation
+
+#### Completeness Checklist
+
+**API Element Documentation**:
+- [ ] Each API element contains appropriate descriptions
+- [ ] Each element includes required metadata tags
+- [ ] All required fields are populated
+- [ ] Optional fields included where beneficial
+
+**Description Quality**:
+- [ ] Descriptions clearly explain purpose
+- [ ] Descriptions clarify functionality
+- [ ] Descriptions guide correct usage
+- [ ] Descriptions avoid implementation details
+
+**Examples & References**:
+- [ ] Examples included where functionality is non-obvious
+- [ ] Cross-references provided to related elements
+- [ ] References are accurate and helpful
+- [ ] Examples demonstrate typical usage patterns
+
+#### Correctness & Consistency Checklist
+
+**UA Developer Review**:
+- [ ] UA Developer reviewed API names for clarity
+- [ ] UA Developer reviewed descriptions for accuracy
+- [ ] Feedback has been documented
+- [ ] Revisions implemented and verified
+
+**Scope & Consistency**:
+- [ ] Scope of descriptions is consistent across similar elements
+- [ ] Quantity of detail is uniform for comparable items
+- [ ] Style and tone match throughout documentation
+- [ ] Terminology is consistent (no synonyms or ambiguity)
+
+**Tag Grouping & Ordering**:
+- [ ] Documentation tags are grouped logically
+- [ ] Tag ordering is consistent across similar elements
+- [ ] Tag order matches style guide recommendations
+- [ ] No redundant or conflicting tags present
+
+**Formatting**:
+- [ ] HTML formatting used correctly throughout
+- [ ] No formatting inconsistencies or errors
+- [ ] Special characters handled properly
+- [ ] Code blocks formatted with syntax highlighting
+
+#### Publication Verification Checklist
+
+**Link Functionality**:
+- [ ] All links direct to intended pages
+- [ ] Links are active and current
+- [ ] No broken or circular references
+- [ ] Cross-references resolve correctly
+
+**Output Quality**:
+- [ ] Generated output functions as expected
+- [ ] Output appears exactly as intended
+- [ ] Navigation works correctly
+- [ ] All dynamic elements function properly
+
+---
+
+## API Review Process
+
+### Core Principle
+
+> "Review texts as early as possible in the development cycle"
+
+**Why Early Review Matters**:
+- Changes early in development are less costly
+- Issues caught early prevent late surprises
+- Teams can iterate more efficiently
+- Quality improves with early feedback
+
+### Key Timing Requirements
+
+| Phase | Timing | Rationale |
+|-------|--------|-----------|
+| **Early Review** | As early as possible in development | Identify issues before significant work invested |
+| **Language Review** | All consumer-facing texts | Ensure clarity and quality |
+| **Final Review** | Before any consumers use API | Prevent bad experiences with first users |
+| **Documentation Generation** | After code/spec review | Accurate representation of implementation |
+
+### Eight Review Areas
+
+#### 1. API Names and Descriptions
+
+**What Gets Reviewed**:
+- Package/API product names
+- Resource and endpoint names
+- Method/operation names
+- Parameter names
+- Response type names
+
+**Review Workflow**:
+1. **Developers** propose names and descriptions
+2. **Product Owners** validate alignment with product vision
+3. **UA Developers** review for:
+   - Clarity and uniqueness
+   - Consistency with other APIs
+   - Correct terminology
+   - Absence of jargon or abbreviations
+4. **Final Approval** after all feedback incorporated
+
+**Review Questions**:
+- Is the name clear without additional context?
+- Does the name accurately reflect what the API does?
+- Is the name consistent with similar APIs?
+- Could any term be ambiguous or confusing?
+
+---
+
+#### 2. Code Comments (Auto-Generated Documentation)
+
+**What Gets Reviewed**:
+- Javadoc comments in Java code
+- JSDoc comments in JavaScript
+- XML documentation comments in .NET
+- Doxygen comments in C/C++
+- OpenAPI descriptions in YAML/JSON specs
+
+**Review Workflow**:
+1. **Developers** write documentation comments in source code
+2. **Developers** verify comments are grammatically correct
+3. **UA Professionals** review comments for:
+   - Technical accuracy
+   - Clarity and usability
+   - Completeness
+   - Consistency with style guide
+4. **Developers** implement feedback
+5. **UA Professionals** verify revisions
+
+**Review Questions**:
+- Are all parameters documented?
+- Are all return values described?
+- Are exceptions/errors documented?
+- Is the description clear to API consumers?
+- Does the example code actually work?
+
+---
+
+#### 3. Manually Written API Documentation
+
+**What Gets Reviewed**:
+- REST API method documentation
+- OData resource documentation
+- Developer guides
+- Integration guides
+- API overview documents
+
+**Review Workflow**:
+1. **Developers** prepare API specifications
+2. **UA Developers** write documentation using templates
+3. **UA Developers** work with product teams on content accuracy
+4. **Developers** review for technical accuracy
+5. **UA Developers** perform final quality check
+6. **Both Teams** validate generated output
+
+See [Manually Written REST and OData API Documentation Reference](manual-templates-guide.md) for detailed template guidance.
+
+**Review Questions**:
+- Is all required information included?
+- Are procedures accurate and complete?
+- Is the structure logical and easy to follow?
+- Are examples correct and testable?
+
+---
+
+#### 4. Code Examples
+
+**What Gets Reviewed**:
+- Code snippets embedded in documentation
+- Sample applications
+- Example scripts
+- Demo code
+- Test code samples
+
+**Review Requirements**:
+- Code snippets **must execute correctly** in development/test environments
+- Examples must demonstrate realistic usage patterns
+- Code must be secure (no hardcoded credentials)
+- Examples must be complete enough to run
+
+**Testing Approach**:
+- Sample files and demo applications are typically tested as part of regular development processes
+- Code review procedures may differ from documentation review
+- Verification focuses on functional correctness, not style
+
+**Review Questions**:
+- Does the code example actually run?
+- Does it demonstrate the intended API usage?
+- Is all necessary setup code included?
+- Are there potential security issues?
+- Could the example mislead developers?
+
+---
+
+#### 5. Error Messages
+
+**What Gets Reviewed**:
+- Error descriptions returned by APIs
+- Exception messages
+- HTTP status code descriptions
+- Validation failure messages
+- Error codes and their meanings
+
+**Why Error Messages Matter**:
+> "Reviewing error messages is a major part of an API review"
+
+Error messages are critical consumer touchpoints that appear in:
+- Application error logs
+- Debugger output
+- User interface alerts
+- API response bodies
+
+**Review Approach**:
+- Apply **people-centric approach** to enhance customer satisfaction
+- Make error messages helpful, not cryptic
+- Provide guidance on resolution when possible
+- Maintain consistent terminology
+
+**Review Questions**:
+- Is the error message clear and actionable?
+- Does it explain what went wrong?
+- Does it suggest how to fix the problem?
+- Is the terminology consistent with other error messages?
+- Is the message free of jargon?
+
+**Good vs. Poor Error Messages**:
+
+| Poor | Good |
+|------|------|
+| "Invalid request" | "Email address format is invalid. Use format: name@example.com" |
+| "Error 400" | "Required field 'firstName' is missing from request body" |
+| "Unauthorized" | "API key is expired. Generate a new key from Developer Dashboard" |
+| "Not found" | "Product with ID 12345 doesn't exist in catalog" |
+
+---
+
+#### 6. Developer Guides
+
+**What Gets Reviewed**:
+- Getting started guides
+- Integration tutorials
+- Conceptual explanations
+- Usage scenarios
+- Best practices documentation
+
+**Review Workflow**:
+1. **Developers** outline key scenarios and tasks
+2. **UA Developers** create guides using template structures
+3. **Subject matter experts** verify technical accuracy
+4. **Beta testers** validate procedures
+5. **Final review** for clarity and completeness
+
+**Review Questions**:
+- Does the guide address customer needs?
+- Are procedures accurate and complete?
+- Is there sufficient explanation for novice users?
+- Are code samples correct and runnable?
+- Is the structure logical and easy to follow?
+
+See [Developer or Service Guides Reference](developer-guides.md) for complete guide structure guidelines.
+
+---
+
+#### 7. Package Names and Descriptions (SAP API Business Hub)
+
+**What Gets Reviewed**:
+- Package titles (grouping of related APIs)
+- Package short descriptions (marketing text)
+- Package overview descriptions
+- Feature lists
+
+**Why Packages Matter**:
+- Packages represent product areas on SAP API Business Hub
+- First impression for API consumers
+- Impact API discoverability and adoption
+
+**Review Workflow**:
+1. **Product Teams** define package scope and purpose
+2. **Marketing/UA** create package descriptions
+3. **Product Owners** verify descriptions reflect product correctly
+4. **UA Developers** review for:
+   - Clarity and appeal
+   - Accurate representation of included APIs
+   - Consistency with related packages
+5. **Final approval** before publishing
+
+**Review Questions**:
+- Is the purpose of the package clear?
+- Do the descriptions accurately describe included APIs?
+- Is it clear who should use this API package?
+- Is the description compelling to potential users?
+
+---
+
+#### 8. OpenAPI Specification (YAML) Files
+
+**What Gets Reviewed**:
+- Info object (title, version, description)
+- Path items and operations
+- Parameter descriptions
+- Response descriptions
+- Schema/component descriptions
+- Security scheme descriptions
+- External documentation references
+
+**Review Workflow**:
+1. **Developers** create or generate OpenAPI spec
+2. **Developers** add/verify description fields
+3. **UA Developers** review spec for:
+   - Complete descriptions throughout
+   - Consistent terminology
+   - Accurate information
+   - Proper formatting
+4. **Both teams** validate rendered output
+5. **Final verification** before publishing to API Hub
+
+**Review Questions**:
+- Are all info fields complete?
+- Are all operations described?
+- Are all parameters documented?
+- Are all response codes explained?
+- Is the spec valid and well-formed?
+
+---
+
+### Review Timing & Collaboration
+
+#### Early Submission Critical
+
+> "Submit APIs for review as early as possible; late submissions put the review at risk"
+
+**Why Early Submission Matters**:
+- Allows adequate review time
+- Enables multiple review iterations
+- Prevents last-minute surprises
+- Improves overall quality
+
+**Timing Recommendations**:
+- **Ideal**: Review at API design phase, before implementation
+- **Acceptable**: Review during active development
+- **Risky**: Review only after development complete
+- **Critical Failure**: Review after consumer adoption begins
+
+#### Developer-UA Collaboration Model
+
+**Developers Responsibility**:
+- Propose clear names and descriptions
+- Write accurate documentation comments
+- Provide API specifications
+- Test code examples thoroughly
+- Review UA feedback promptly
+- Implement feedback completely
+
+**UA Responsibility**:
+- Review for clarity and consistency
+- Ensure language is grammatically correct
+- Verify descriptions match consumer needs
+- Check compliance with style guide
+- Test rendered output
+- Provide constructive feedback
+
+**Communication**:
+- Regular check-ins during development
+- Clear feedback with specific examples
+- Timely responses to questions
+- Documentation of decisions and changes
+
+---
+
+## Guidelines for Development Teams
+
+### Best Practices Overview
+
+Development teams should follow these guidelines to achieve superior API quality:
+
+1. **Prepare API specifications** before implementation begins
+2. **Plan API reviews** in the same development cycle as API implementation
+3. **Track review activities** in development backlog for transparency
+4. **Submit early** for review to enable adequate assessment
+5. **Implement feedback completely** to gain full review benefits
+6. **Implement before consumer use** to prevent bad experiences
+7. **Perform quality checks** using the API Quality Checklist
+
+### 1. Prepare API Specifications
+
+**Timing**: Before or early during development
+
+**What to Include**:
+- API purpose and use cases
+- Resource/endpoint definitions
+- Parameter specifications
+- Response structures
+- Error conditions
+- Security requirements
+- Integration points
+
+**Why It Matters**:
+- Establishes clear expectations
+- Enables early UA review
+- Prevents misalignment with consumers
+- Facilitates documentation planning
+
+**Recommendations**:
+- Create formal specification document
+- Share with product team for feedback
+- Incorporate use cases and requirements
+- Include examples and scenarios
+
+---
+
+### 2. Plan API Reviews in Development Cycle
+
+**Integration into Workflow**:
+```
+Specification → Design Review → Development → Code Review →
+Documentation Review → Testing → Consumer Pilot → Production
+```
+
+**Key Principle**:
+> "Plan API reviews in the same development cycle as the API implementation"
+
+**Timing**:
+- Start documentation planning early (not after coding)
+- Schedule UA review before or during development
+- Allocate time for iteration and revision
+- Plan for multiple review rounds if needed
+
+**Planning Questions**:
+- When will API specs be ready for review?
+- Who will review (which UA developers)?
+- How many review iterations are needed?
+- What's the timeline for feedback?
+- When must implementation be complete?
+
+---
+
+### 3. Include API Reviews in Backlog
+
+**Transparency & Tracking**:
+```
+Development Backlog:
+├─ Feature Development
+│  ├─ API Implementation: 5 days
+│  ├─ UA Documentation Review: 3 days
+│  ├─ Feedback Implementation: 2 days
+│  └─ Final Validation: 1 day
+├─ Code Review & Testing
+└─ Production Deployment
+```
+
+**Why Include in Backlog**:
+- Makes review process visible to all stakeholders
+- Allows proper resource planning
+- Enables accurate timeline estimation
+- Prevents documentation from being overlooked
+- Tracks completion and dependencies
+
+**Backlog Item Details**:
+- Clear acceptance criteria
+- Resource assignments (UA developer)
+- Timeline estimates
+- Dependency tracking
+- Status updates
+
+---
+
+### 4. Submit APIs Early for Review
+
+**The Early Review Advantage**:
+
+| Submission Timing | Review Outcome | Quality Impact |
+|-------------------|---|---|
+| **Design Phase** | Design feedback incorporated | Highest quality |
+| **Active Development** | Rapid iteration possible | High quality |
+| **Pre-Release** | Limited time for revision | Medium quality |
+| **Post-Release** | Consumer confusion | Low quality |
+
+**What "Early" Means**:
+- As soon as specifications are stable
+- Before development is fully complete
+- Definitely before any consumer access
+- With adequate time for multiple iterations
+
+**Early Submission Checklist**:
+- [ ] API specification document exists
+- [ ] Requirements are clearly defined
+- [ ] Use cases documented
+- [ ] Product team alignment achieved
+- [ ] Schedule allows time for feedback
+
+**Communication**:
+- Notify UA team of upcoming API
+- Schedule preliminary review meeting
+- Discuss timeline and expectations
+- Identify potential issues early
+
+---
+
+### 5. Implement Feedback Completely
+
+**Critical Success Factor**:
+> "Implement the review feedback in full, otherwise you lose part of its benefits"
+
+**Why Complete Implementation Matters**:
+- Partial implementation wastes reviewer time
+- Inconsistent implementation confuses consumers
+- Undermines value of review process
+- Leads to repeated issues in future APIs
+
+**Implementation Process**:
+1. **Document feedback** in tracked format
+2. **Categorize issues** by priority
+3. **Assign responsibility** to team members
+4. **Plan implementation** with timeline
+5. **Execute changes** completely
+6. **Verify** against original feedback
+7. **Report completion** to UA team
+
+**Handling Disagreements**:
+- Discuss concerns with UA reviewer
+- Present rationale for alternative approach
+- Seek consensus or escalate if needed
+- Document final decision and reasoning
+
+**Examples**:
+
+| Feedback | Partial Implementation | Complete Implementation |
+|----------|---|---|
+| "Description needs clarity" | Fix one of three unclear points | Fix all descriptions, verify all are clear |
+| "API naming inconsistent" | Rename some APIs | Rename all affected APIs, verify consistency |
+| "Examples have errors" | Fix obvious errors | Test all examples, fix all issues |
+
+---
+
+### 6. Implement Before Consumer Use
+
+**Critical Timing**:
+> "Implement the review before APIs are used by any consumers (internal and external)"
+
+**Why This Matters**:
+- First impressions are critical
+- Early adopters set tone for API adoption
+- Documentation bugs damage credibility
+- Bad examples create bad implementations
+
+**Consumer Scope**:
+- External API consumers
+- Internal teams using API
+- Beta testers and pilot programs
+- Demo users and evaluators
+
+**Validation Approach**:
+1. Complete all feedback implementation
+2. Test thoroughly in staging environment
+3. Perform final quality check (using checklist)
+4. Release to limited audience first (internal pilot)
+5. Gather feedback from initial users
+6. Make any final adjustments
+7. Release to general audience
+
+---
+
+### 7. Perform Quality Checks
+
+**Final Verification Step**:
+
+Before releasing any API, use the **API Quality Checklist** to verify:
+- ✅ All documentation tags present
+- ✅ Descriptions are clear and complete
+- ✅ Examples are accurate and work correctly
+- ✅ Naming is consistent and follows conventions
+- ✅ Security and privacy requirements met
+- ✅ Links and cross-references functional
+- ✅ Output renders correctly
+- ✅ UA review completed and feedback implemented
+
+**Quality Check Responsibility**:
+- **Primary**: Developers performing final self-check
+- **Secondary**: UA team performing verification
+- **Final**: Joint sign-off before release
+
+**Escalation**:
+If quality check fails:
+1. Identify specific issues
+2. Prioritize by severity
+3. Assign to team members
+4. Re-test changes
+5. Repeat quality check until passing
+6. Document resolution
+
+---
+
+## Best Practices
+
+### For Developers
+
+#### 1. Write Clear API Names
+```
+✅ GOOD: "createCustomer", "getOrderHistory", "updateInventory"
+❌ BAD: "create", "get", "handleOrderDataRequest"
+```
+
+#### 2. Write Precise Parameter Descriptions
+```
+✅ GOOD: "Email address of customer in format name@example.com"
+❌ BAD: "Customer email"
+```
+
+#### 3. Include Realistic Examples
+```
+✅ GOOD: Example includes actual expected inputs/outputs
+❌ BAD: Placeholder example or incorrect syntax
+```
+
+#### 4. Implement All Feedback
+```
+✅ GOOD: Every feedback item addressed with specific changes
+❌ BAD: Ignore feedback or implement partially
+```
+
+#### 5. Test Code Examples
+```
+✅ GOOD: Every code example runs successfully
+❌ BAD: Examples contain errors or pseudo-code
+```
+
+### For UA/Technical Writers
+
+#### 1. Review Early and Often
+```
+✅ GOOD: Multiple review touchpoints during development
+❌ BAD: Single review at end of project
+```
+
+#### 2. Focus on Clarity
+```
+✅ GOOD: Feedback includes specific clarity improvements
+❌ BAD: Generic comments like "make it clearer"
+```
+
+#### 3. Provide Examples
+```
+✅ GOOD: Show good and bad examples in feedback
+❌ BAD: Point out problems without solutions
+```
+
+#### 4. Document Decisions
+```
+✅ GOOD: Track all feedback and how it was addressed
+❌ BAD: Informal discussions with no record
+```
+
+#### 5. Verify Implementation
+```
+✅ GOOD: Re-review revised documentation
+❌ BAD: Assume feedback was implemented correctly
+```
+
+### For Product Managers
+
+#### 1. Allocate Time for Documentation
+```
+✅ GOOD: Documentation review scheduled in sprint planning
+❌ BAD: Documentation treated as afterthought
+```
+
+#### 2. Include in Acceptance Criteria
+```
+✅ GOOD: API feature not "done" until documentation reviewed
+❌ BAD: Documentation quality not tracked in definition of done
+```
+
+#### 3. Involve UA from Start
+```
+✅ GOOD: UA team consulted during API design
+❌ BAD: UA team involved only at end
+```
+
+#### 4. Prioritize Based on Impact
+```
+✅ GOOD: Public-facing APIs get more review resources
+❌ BAD: All APIs treated equally regardless of visibility
+```
+
+#### 5. Measure Quality Outcomes
+```
+✅ GOOD: Track documentation-related support tickets
+❌ BAD: No metrics on documentation effectiveness
+```
+
+---
+
+## Process Flowcharts
+
+### Overall API Documentation Process
+
+```
+START: New API Development
+  │
+  ├─→ Phase 1: Specification & Planning
+  │   ├─ Create API specification
+  │   ├─ Define use cases
+  │   ├─ Plan documentation approach
+  │   └─ Schedule UA review
+  │
+  ├─→ Phase 2: Development & Documentation
+  │   ├─ Develop API implementation
+  │   ├─ Write documentation comments
+  │   ├─ Create code examples
+  │   └─ Early submission to UA
+  │
+  ├─→ Phase 3: UA Review & Feedback
+  │   ├─ UA reviews names and descriptions
+  │   ├─ UA reviews code comments
+  │   ├─ UA reviews examples
+  │   ├─ UA provides detailed feedback
+  │   └─ Teams discuss and align
+  │
+  ├─→ Phase 4: Implementation & Revision
+  │   ├─ Implement all feedback
+  │   ├─ Revise documentation
+  │   ├─ Test revised examples
+  │   └─ Re-submit if major changes
+  │
+  ├─→ Phase 5: Quality Check & Validation
+  │   ├─ Run API Quality Checklist
+  │   ├─ Verify all items checked
+  │   ├─ Resolve any issues
+  │   └─ Obtain final sign-off
+  │
+  ├─→ Phase 6: Publication & Deployment
+  │   ├─ Deploy to staging
+  │   ├─ Internal pilot with early adopters
+  │   ├─ Gather initial feedback
+  │   ├─ Make final adjustments if needed
+  │   └─ Deploy to production
+  │
+  └─→ END: API Published & Available
+```
+
+### Developer Submission Workflow
+
+```
+Developer: Ready to Submit for Review
+  │
+  ├─ Check: Documentation complete?
+  │  └─ NO: Complete documentation → return
+  │
+  ├─ Check: Code examples tested?
+  │  └─ NO: Test and fix → return
+  │
+  ├─ Check: API names reviewed internally?
+  │  └─ NO: Review and refine → return
+  │
+  ├─→ Submit to UA Team
+  │   │
+  │   ├─ UA: Initial review
+  │   │   ├─ Review names & descriptions
+  │   │   ├─ Review code comments
+  │   │   ├─ Review examples
+  │   │   └─ Compile feedback
+  │   │
+  │   ├─ UA: Provide Feedback
+  │   │   ├─ High priority items (blocking)
+  │   │   ├─ Medium priority items (important)
+  │   │   └─ Low priority items (nice to have)
+  │   │
+  │   └─→ Developer: Implement Feedback
+  │       ├─ Address high priority items first
+  │       ├─ Implement all feedback items
+  │       ├─ Test changes thoroughly
+  │       ├─ Document what was changed
+  │       └─ Re-submit if significant changes
+  │
+  └─→ Approval & Quality Check
+      ├─ Final review of revisions
+      ├─ Quality checklist validation
+      └─ Sign-off for publication
+```
+
+### UA Review Workflow
+
+```
+UA Team Receives Submission
+  │
+  ├─→ Initial Triage
+  │   ├─ Assign to reviewer
+  │   ├─ Schedule review time
+  │   ├─ Request clarification if needed
+  │   └─ Set expectations for timeline
+  │
+  ├─→ Detailed Review Phase
+  │   ├─ Review API names & descriptions
+  │   │  └─ Check clarity, consistency, completeness
+  │   │
+  │   ├─ Review code comments
+  │   │  └─ Check documentation tags, accuracy
+  │   │
+  │   ├─ Review code examples
+  │   │  └─ Test execution, accuracy
+  │   │
+  │   ├─ Review error messages
+  │   │  └─ Check clarity, helpfulness
+  │   │
+  │   └─ Review any supporting documentation
+  │      └─ Check structure, completeness
+  │
+  ├─→ Compile Feedback
+  │   ├─ Organize by area reviewed
+  │   ├─ Prioritize findings
+  │   ├─ Prepare examples
+  │   └─ Schedule feedback discussion
+  │
+  ├─→ Present Feedback to Developer
+  │   ├─ Explain findings and rationale
+  │   ├─ Discuss alternative approaches
+  │   ├─ Clarify expectations
+  │   └─ Establish implementation timeline
+  │
+  └─→ Track Implementation
+      ├─ Monitor feedback completion
+      ├─ Answer developer questions
+      ├─ Verify revisions
+      └─ Sign-off when complete
+```
+
+### Quality Checklist Review Workflow
+
+```
+Quality Checklist Review
+  │
+  ├─→ Auto-Generated Documentation Path
+  │   │
+  │   ├─ Creating/Editing Specification
+  │   │  ├─ Tags appropriate? ──→ NO: Add/fix tags
+  │   │  ├─ Comments complete? ──→ NO: Add comments
+  │   │  ├─ Descriptions clear? ──→ NO: Improve
+  │   │  ├─ Examples included? ──→ NO: Add examples
+  │   │  └─ No sensitive data? ──→ NO: Remove
+  │   │
+  │   └─ Reviewing Specification
+  │      ├─ Consistent descriptions? ──→ NO: Unify
+  │      ├─ Tags grouped/ordered? ──→ NO: Reorganize
+  │      ├─ UA reviewed names/descriptions? ──→ NO: Get review
+  │      ├─ Formatting correct? ──→ NO: Fix formatting
+  │      ├─ Compiles without errors? ──→ NO: Fix errors
+  │      ├─ All links work? ──→ NO: Fix links
+  │      └─ Output looks expected? ──→ NO: Adjust
+  │
+  └─→ Manually Written Documentation Path
+      │
+      ├─ Completeness Check
+      │  ├─ All elements documented? ──→ NO: Add documentation
+      │  ├─ All required tags? ──→ NO: Add tags
+      │  ├─ Descriptions clear? ──→ NO: Improve clarity
+      │  └─ Examples/references included? ──→ NO: Add content
+      │
+      ├─ Correctness Check
+      │  ├─ UA reviewed names/descriptions? ──→ NO: Get review
+      │  ├─ Descriptions consistent? ──→ NO: Standardize
+      │  ├─ Tags ordered consistently? ──→ NO: Reorder
+      │  └─ HTML formatting correct? ──→ NO: Fix formatting
+      │
+      └─ Publication Check
+         ├─ All links functional? ──→ NO: Fix links
+         └─ Output works as expected? ──→ NO: Fix output
+
+═══════════════════════════════════════════════════════════
+ALL CHECKS PASSED → READY FOR PUBLICATION
+═══════════════════════════════════════════════════════════
+```
+
+---
+
+## Review Checklists & Templates
+
+### Quick Reference: API Review Decision Tree
+
+```
+What are you reviewing?
+│
+├─ API Names & Descriptions?
+│  └─ See: Quick Checklist for Names & Descriptions (below)
+│
+├─ Auto-Generated Documentation (Code Comments)?
+│  └─ See: Quick Checklist for Code Comments (below)
+│
+├─ Manually Written Documentation?
+│  └─ See: Quick Checklist for Manual Documentation (below)
+│
+├─ Code Examples?
+│  └─ See: Quick Checklist for Code Examples (below)
+│
+├─ Error Messages?
+│  └─ See: Quick Checklist for Error Messages (below)
+│
+├─ Developer Guides?
+│  └─ See: Quick Checklist for Developer Guides (below)
+│
+├─ Package Information?
+│  └─ See: Quick Checklist for Package Information (below)
+│
+└─ OpenAPI Specification Files?
+   └─ See: Quick Checklist for OpenAPI Files (below)
+```
+
+### Quick Checklist: API Names & Descriptions
+
+**Use this when**: Reviewing proposed API/resource/method names and their descriptions.
+
+**Reviewer**: UA Developer or Product Manager
+
+**Time Required**: 30 minutes - 1 hour per API
+
+**Checklist**:
+
+- [ ] **Name Clarity**: Is the name clear without additional context?
+- [ ] **Name Accuracy**: Does the name accurately reflect what the API does?
+- [ ] **Name Consistency**: Is the name consistent with other similar APIs?
+- [ ] **No Ambiguity**: Could any term be misinterpreted?
+- [ ] **No Jargon**: Are technical terms explained if used?
+- [ ] **Description Accuracy**: Does the description match the implementation?
+- [ ] **Description Completeness**: Does the description explain all key aspects?
+- [ ] **Purpose Clear**: Is the purpose immediately obvious?
+- [ ] **Usage Context**: Is it clear when/why to use this API?
+- [ ] **Related APIs**: Are relationships to other APIs mentioned?
+
+**If Issues Found**:
+1. Document specific feedback
+2. Suggest improvements (provide examples)
+3. Discuss with developer
+4. Document final decision
+5. Track implementation
+
+---
+
+### Quick Checklist: Code Comments (Auto-Generated Documentation)
+
+**Use this when**: Reviewing Javadoc, JSDoc, XML doc comments, or Doxygen comments.
+
+**Reviewer**: UA Developer or Senior Developer
+
+**Time Required**: 1-2 hours per API with 5-10 methods
+
+**Checklist**:
+
+**Overview & Completeness**:
+- [ ] All public methods documented?
+- [ ] All public classes documented?
+- [ ] All public attributes documented?
+- [ ] All parameters documented?
+- [ ] All return values documented?
+- [ ] All exceptions documented?
+
+**Description Quality**:
+- [ ] Descriptions are clear and unambiguous?
+- [ ] Descriptions avoid implementation details?
+- [ ] Descriptions use consistent terminology?
+- [ ] Descriptions explain purpose and usage?
+- [ ] No unnecessary technical jargon?
+
+**Tag Usage**:
+- [ ] Appropriate tags used for language?
+- [ ] Tags in correct order (consistent)?
+- [ ] Tag information is complete?
+- [ ] No conflicting or redundant tags?
+- [ ] Examples provided for complex concepts?
+
+**Code Examples**:
+- [ ] Examples included where helpful?
+- [ ] Examples are accurate?
+- [ ] Examples follow best practices?
+- [ ] Examples actually compile/run?
+
+**Security & Privacy**:
+- [ ] No hardcoded credentials in examples?
+- [ ] No sensitive data in samples?
+- [ ] Examples don't expose internal details?
+
+**If Issues Found**:
+1. Categorize by severity
+2. Provide specific examples
+3. Show corrected version if possible
+4. Discuss with developer
+5. Schedule re-review after fixes
+
+---
+
+### Quick Checklist: Manually Written Documentation
+
+**Use this when**: Reviewing REST API docs, OData docs, developer guides, or integration guides.
+
+**Reviewer**: UA Developer and Product Owner
+
+**Time Required**: 2-4 hours depending on length
+
+**Checklist**:
+
+**Structure & Organization**:
+- [ ] Logical progression of topics?
+- [ ] Clear navigation between sections?
+- [ ] Appropriate use of headings?
+- [ ] Related content linked together?
+- [ ] Search-friendly structure?
+
+**Content Completeness**:
+- [ ] All required sections included?
+- [ ] Each endpoint/method documented?
+- [ ] Parameters documented?
+- [ ] Response codes documented?
+- [ ] Examples provided?
+
+**Description Quality**:
+- [ ] Descriptions clear and accurate?
+- [ ] Terminology consistent?
+- [ ] Avoid implementation details?
+- [ ] Address typical use cases?
+- [ ] Explain error conditions?
+
+**Code Examples**:
+- [ ] Examples accurate and complete?
+- [ ] Examples runnable without errors?
+- [ ] Examples show realistic usage?
+- [ ] Examples include error handling?
+- [ ] Examples have explanatory comments?
+
+**Technical Accuracy**:
+- [ ] Descriptions match actual behavior?
+- [ ] Examples work as documented?
+- [ ] No outdated information?
+- [ ] All links functional?
+- [ ] Dependencies clearly stated?
+
+**If Issues Found**:
+1. Provide detailed feedback with examples
+2. Suggest structural improvements
+3. Offer example revisions if needed
+4. Prioritize by impact on usability
+5. Schedule revision and re-review
+
+---
+
+### Quick Checklist: Code Examples
+
+**Use this when**: Reviewing code snippets, sample applications, or demo code.
+
+**Reviewer**: Senior Developer or QA Lead
+
+**Time Required**: 1-2 hours per example
+
+**Checklist**:
+
+**Functionality**:
+- [ ] Code compiles/runs successfully?
+- [ ] Code produces expected output?
+- [ ] Dependencies properly documented?
+- [ ] Setup instructions complete?
+- [ ] Example doesn't require undocumented setup?
+
+**Correctness**:
+- [ ] Logic is correct and appropriate?
+- [ ] Code follows best practices?
+- [ ] Error handling included?
+- [ ] Edge cases considered?
+- [ ] Performance reasonable?
+
+**Security**:
+- [ ] No hardcoded credentials or keys?
+- [ ] No sensitive data in examples?
+- [ ] No security vulnerabilities?
+- [ ] Security assumptions documented?
+- [ ] Proper input validation shown?
+
+**Clarity**:
+- [ ] Code is readable and well-commented?
+- [ ] Variable names are clear?
+- [ ] Complex logic explained?
+- [ ] Purpose of example clear?
+- [ ] Related examples cross-referenced?
+
+**Completeness**:
+- [ ] Example shows the intended use case?
+- [ ] All required steps included?
+- [ ] Success and failure paths shown?
+- [ ] Expected output documented?
+- [ ] Variations explained?
+
+**If Issues Found**:
+1. Test locally to confirm issues
+2. Provide corrected version
+3. Explain the problem and solution
+4. Schedule testing of revised example
+5. Verify fix with developer
+
+---
+
+### Quick Checklist: Error Messages
+
+**Use this when**: Reviewing error messages, exception messages, or API error responses.
+
+**Reviewer**: UA Developer and UX Designer
+
+**Time Required**: 30 minutes - 1 hour
+
+**Checklist**:
+
+**Clarity**:
+- [ ] Error message is clear and understandable?
+- [ ] Explains what went wrong?
+- [ ] No cryptic codes or jargon?
+- [ ] Appropriate for target audience?
+- [ ] Same error uses consistent message?
+
+**Actionability**:
+- [ ] Message suggests how to fix the problem?
+- [ ] Provides next steps where possible?
+- [ ] Links to relevant documentation?
+- [ ] Error code provided for support?
+- [ ] Technical details available but not overwhelming?
+
+**Tone & Quality**:
+- [ ] Tone is professional and helpful?
+- [ ] Message is not accusatory?
+- [ ] Grammar and spelling correct?
+- [ ] Consistent with other error messages?
+- [ ] Localization considered (if applicable)?
+
+**Context**:
+- [ ] Error message appropriate for the failure?
+- [ ] Related errors use related messages?
+- [ ] Severity level clear?
+- [ ] Recovery path documented?
+
+**Examples**:
+
+| Error | Poor Message | Good Message |
+|-------|---|---|
+| Invalid Email | "Invalid input" | "Email format is invalid. Use format: name@example.com" |
+| Missing Field | "Bad request" | "Required field 'firstName' is missing from request body" |
+| API Key Expired | "Unauthorized" | "API key expired on 2024-01-15. Generate a new key from Developer Dashboard" |
+| Resource Not Found | "404" | "Product with ID 'abc123' not found in your account" |
+
+**If Issues Found**:
+1. Identify specific message problems
+2. Provide improved version
+3. Check related error messages for consistency
+4. Discuss implications with developer
+5. Update all similar error messages
+
+---
+
+### Review Feedback Template
+
+**Use this template** when providing feedback on API documentation.
+
+```
+REVIEWER: [Name]
+REVIEW DATE: [Date]
+API NAME: [API or Resource Name]
+REVIEW AREA: [ ] Names  [ ] Descriptions  [ ] Code Comments  [ ] Examples  [ ] Errors  [ ] Other: ____
+
+FINDINGS SUMMARY:
+[Brief overview of key issues and strengths]
+
+PRIORITY 1 - BLOCKING ISSUES (Must fix before publication):
+1. [Issue Description]
+   Current: [Current text/implementation]
+   Recommended: [Suggested improvement]
+
+2. [Issue Description]
+   Current: [Current text/implementation]
+   Recommended: [Suggested improvement]
+
+PRIORITY 2 - IMPORTANT (Should fix before publication):
+1. [Issue Description]
+   Current: [Current text/implementation]
+   Recommended: [Suggested improvement]
+
+PRIORITY 3 - NICE TO HAVE (Optional improvements):
+1. [Suggestion]
+
+STRENGTHS (What was done well):
+- [Positive feedback]
+- [Positive feedback]
+
+NEXT STEPS:
+1. Developer implements Priority 1 and 2 fixes
+2. Resubmit for verification
+3. Schedule publication once approved
+
+REVIEWER SIGN-OFF:
+[ ] Ready for publication (all issues resolved)
+[ ] Pending revision (will re-review after fixes)
+```
+
+---
+
+## Common Review Findings
+
+### Common Finding #1: Unclear Descriptions
+
+**Problem**: API descriptions are vague or don't explain functionality clearly.
+
+**Examples of Issues**:
+```
+❌ POOR: "Manages user data"
+✅ GOOD: "Creates, updates, retrieves, and deletes user profiles in the system"
+
+❌ POOR: "Processes information"
+✅ GOOD: "Analyzes sales data to identify top-performing products by region"
+
+❌ POOR: "Handles requests"
+✅ GOOD: "Accepts order requests, validates inventory, and returns fulfillment status"
+```
+
+**How to Address**:
+1. Ask developer: "What does this API actually do?"
+2. Provide concrete example of better description
+3. Explain impact: "Developers need clear understanding of what to use"
+4. Review similar APIs for consistency
+5. Verify fix: Re-read improved description without API code
+
+**Prevention**:
+- Train developers on description guidelines
+- Use review templates with examples
+- Reference style guide during development
+- Early review catches vagueness quickly
+
+---
+
+### Common Finding #2: Inconsistent Terminology
+
+**Problem**: Same concepts referred to by different names across documentation.
+
+**Examples of Issues**:
+```
+❌ INCONSISTENT:
+   - "customer ID" in one place
+   - "customer identifier" in another
+   - "cust_id" in another
+
+✅ CONSISTENT: Always use "customer ID"
+```
+
+**How to Address**:
+1. Create terminology list for API
+2. Search documentation for all variations
+3. Replace with standard term consistently
+4. Update documentation templates to use standard term
+5. Document approved terminology
+
+**Prevention**:
+- Create glossary before starting documentation
+- Use search-and-replace to ensure consistency
+- Review with UA team early
+- Use automated tools to check consistency
+
+---
+
+### Common Finding #3: Incomplete Parameter Documentation
+
+**Problem**: Parameters documented but missing important details.
+
+**Examples of Issues**:
+```
+❌ INCOMPLETE:
+   Parameter: userID (string)
+
+✅ COMPLETE:
+   Parameter: userID (string, required)
+   Description: The unique identifier for the user in format "USER-12345"
+   Example: "USER-00789"
+   Constraints: Alphanumeric, 10 characters maximum, case-sensitive
+```
+
+**How to Address**:
+1. Use parameter documentation template
+2. For each parameter, verify:
+   - Name and type documented?
+   - Required vs. optional clear?
+   - Format/constraints specified?
+   - Example provided?
+   - Related parameters mentioned?
+3. Test documentation against real use
+4. Verify with code implementation
+
+**Prevention**:
+- Use automated extraction from source code
+- Document parameters as code is written
+- Early review catches incompleteness
+- Use parameter template consistently
+
+---
+
+### Common Finding #4: Code Examples That Don't Work
+
+**Problem**: Code examples have errors or don't actually run successfully.
+
+**Examples of Issues**:
+```
+❌ BROKEN:
+   const user = api.getUser(userId)
+   // Missing: This line needs error handling
+   // Missing: Actual error handling shown
+
+✅ WORKING:
+   try {
+      const user = await api.getUser(userId)
+      console.log(`Retrieved user: ${user.name}`)
+   } catch (error) {
+      console.error(`Failed to retrieve user: ${error.message}`)
+   }
+```
+
+**How to Address**:
+1. Test every code example locally
+2. Ensure all dependencies are available
+3. Include all necessary imports/setup
+4. Show error handling
+5. Verify output matches description
+6. Include complete, runnable code (not snippets)
+7. Document any dependencies or prerequisites
+
+**Prevention**:
+- Require developer to test example before submission
+- Use linters/compilers to verify syntax
+- Include examples in automated tests
+- Re-test examples before each publication
+- Use code example templates
+
+---
+
+### Common Finding #5: Security Issues in Examples
+
+**Problem**: Examples include hardcoded credentials, sensitive data, or security vulnerabilities.
+
+**Examples of Issues**:
+```
+❌ SECURITY RISK:
+   const apiKey = "sk_live_4eC39HqLyjWDarhtT657a835"
+   const email = "john.smith@company.com"
+
+✅ SECURE:
+   const apiKey = process.env.API_KEY  // Load from environment
+   const email = "user@example.com"    // Generic example
+```
+
+**How to Address**:
+1. Remove all real credentials from examples
+2. Use environment variables for keys/credentials
+3. Use generic example data (no real names/emails)
+4. Document security best practices
+5. Show proper authentication patterns
+6. Include security notes in documentation
+
+**Prevention**:
+- Security review as part of example testing
+- Linting tools to detect hardcoded secrets
+- Code review process checks for credentials
+- Templates show correct patterns
+- Documentation warns about security
+
+---
+
+### Common Finding #6: Missing Examples for Complex Operations
+
+**Problem**: Complex functionality documented but no examples of how to use it.
+
+**Examples**:
+```
+❌ NO EXAMPLE:
+   "This endpoint supports complex filtering with nested conditions"
+   [No example showing how to structure the filter]
+
+✅ WITH EXAMPLE:
+   "This endpoint supports complex filtering with nested conditions"
+
+   Example: Filter orders from 2024 where total > $1000:
+   {
+     "filter": {
+       "date": { "gte": "2024-01-01" },
+       "total": { "gt": 1000 }
+     }
+   }
+```
+
+**How to Address**:
+1. Identify complex functionality
+2. Create example scenarios
+3. Show request and response
+4. Explain what makes it complex
+5. Include variations
+6. Test example works correctly
+
+**Prevention**:
+- Review templates include example requirements
+- Early review identifies complex areas
+- Developer provides examples during development
+- QA tests complex scenarios
+- Documentation includes real-world use cases
+
+---
+
+### Common Finding #7: Inconsistent Error Response Format
+
+**Problem**: Error messages format and details vary inconsistently.
+
+**Examples of Issues**:
+```
+❌ INCONSISTENT:
+   Error 1: "User not found"
+   Error 2: { "code": "PRODUCT_NOT_FOUND", "message": "Product with ID 123 not found" }
+   Error 3: { "error": { "type": "INVALID_REQUEST", "description": "Invalid request format" } }
+
+✅ CONSISTENT:
+   {
+     "code": "ERROR_CODE",
+     "message": "Human-readable description",
+     "details": { /* context */ }
+   }
+```
+
+**How to Address**:
+1. Define standard error response format
+2. Document format with examples
+3. Apply consistently to all error codes
+4. Include all error codes in documentation
+5. Organize errors logically (by category)
+6. Explain how to handle each error type
+
+**Prevention**:
+- Establish error format standard early
+- Use error response templates
+- Code generation tools enforce format
+- Review catches inconsistencies
+- Documentation tools validate format
+
+---
+
+### Common Finding #8: Missing or Incorrect Link References
+
+**Problem**: Links in documentation point to wrong locations or are broken.
+
+**Examples of Issues**:
+```
+❌ BROKEN:
+   "See [authentication guide](../auth-guide) for details"
+   (File doesn't exist at that location)
+
+✅ WORKING:
+   "See [authentication guide](/docs/auth-guide.md) for details"
+   (Link verified to work)
+```
+
+**How to Address**:
+1. Document link strategy (relative vs. absolute URLs)
+2. Use link checking tools
+3. Test all links before publication
+4. Use consistent naming conventions
+5. Document link structure
+6. Update links when files move
+7. Use canonical URLs where possible
+
+**Prevention**:
+- Automated link checking in CI/CD
+- Use link validator tools
+- Document file structure clearly
+- Version links in documentation
+- Use linkers (if available) instead of hand-coded links
+- Regular link audits
+
+---
+
+### Common Finding #9: API Description Repeats Parameter Details
+
+**Problem**: API description repeats information already documented in parameter section.
+
+**Examples of Issues**:
+```
+❌ REPETITIVE:
+   Operation: "Creates a new user with firstName, lastName, and email"
+
+   Parameters:
+   - firstName (string): The user's first name
+   - lastName (string): The user's last name
+   - email (string): The user's email address
+
+✅ FOCUSED:
+   Operation: "Creates a new user account"
+
+   Parameters:
+   - firstName (string): The user's first name
+   - lastName (string): The user's last name
+   - email (string): The user's email address
+```
+
+**How to Address**:
+1. Review API descriptions
+2. Remove details documented elsewhere
+3. Keep description focused on purpose
+4. Reference parameter section if needed
+5. Ensure description adds value
+6. Check for redundancy with all text
+
+**Prevention**:
+- Establish style guide for description content
+- Review templates show good/bad examples
+- Early review catches redundancy
+- Documentation generation removes duplication
+- Linting tools identify repetition
+
+---
+
+### Common Finding #10: Insufficient Error Documentation
+
+**Problem**: API errors documented but lacking guidance on recovery or causes.
+
+**Examples of Issues**:
+```
+❌ INSUFFICIENT:
+   400: Bad Request
+   401: Unauthorized
+   404: Not Found
+
+✅ COMPLETE:
+   400: Bad Request - Request validation failed
+       Common causes: Missing required field, invalid format
+       Solution: Check request structure matches schema
+
+   401: Unauthorized - Authentication failed
+       Common causes: Missing/expired API key, insufficient permissions
+       Solution: Verify API key in Authorization header
+
+   404: Not Found - Resource doesn't exist
+       Common causes: Invalid resource ID, resource was deleted
+       Solution: Verify resource ID matches existing record
+```
+
+**How to Address**:
+1. Document each error code with:
+   - What triggered the error
+   - Common causes
+   - How to fix it
+2. Provide recovery steps
+3. Include troubleshooting guidance
+4. Link to related documentation
+5. Provide examples of valid requests
+
+**Prevention**:
+- Error documentation template with required sections
+- Code review validates error handling
+- QA tests error scenarios
+- Documentation reviews check completeness
+- Real-world support tickets inform error docs
+
+---
+
+## Summary of Review Areas and Responsibilities
+
+| Review Area | Primary Reviewer | Secondary Reviewer | Frequency | Effort |
+|---|---|---|---|---|
+| **API Names** | UA Developer | Product Manager | Early design | 30 min |
+| **Descriptions** | UA Developer | Senior Developer | Throughout | 1-2 hours |
+| **Code Comments** | UA Developer | Developer Lead | During development | 2-4 hours |
+| **Code Examples** | Senior Developer | QA Lead | Before publication | 1-2 hours |
+| **Error Messages** | UA Developer | UX Designer | Before publication | 30 min - 1 hour |
+| **Manual Documentation** | UA Developer | Product Owner | Throughout | 2-4 hours |
+| **OpenAPI Specs** | UA Developer | Product Team | Before publication | 1-2 hours |
+| **Security/Privacy** | Security Team | Developer | Before publication | 30 min - 1 hour |
+
+---
+
+## Key Principles to Remember
+
+### 1. Quality Starts with Clear Planning
+- Prepare specifications before implementation
+- Plan reviews in the development cycle
+- Allocate adequate time for feedback and revision
+
+### 2. Early Review Prevents Major Issues
+- Review at design stage, not at end
+- Early feedback is easier and cheaper to implement
+- Prevents last-minute surprises
+
+### 3. Complete Feedback Implementation is Essential
+- Partial implementation wastes reviewer time
+- Undermines value of the review process
+- Leads to recurring issues in future APIs
+
+### 4. Consumer Focus Drives Quality
+- Document for consumers, not for developers
+- Use plain language
+- Provide practical examples
+- Address common questions
+
+### 5. Collaboration Across Teams is Critical
+- Developers write the code and comments
+- UA professionals ensure clarity and consistency
+- Product teams provide business context
+- Everyone works together for quality
+
+### 6. Documentation is Never "Done"
+- Review new versions of APIs
+- Update documentation when APIs change
+- Fix issues discovered by consumers
+- Iterate continuously for improvement
+
+---
+
+## References
+
+- **SAP API Style Guide**: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide)
+- **OpenAPI Specification**: [https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html)
+- **OData v4.01**: [https://www.odata.org/documentation/](https://www.odata.org/documentation/)
+- **SAP API Business Hub**: [https://api.sap.com/](https://api.sap.com/)
+
+---
+
+**Document Version**: 1.0.0
+**Last Updated**: 2025-11-21
+**Status**: Complete
+**License**: GPL-3.0
+**Maintainer**: SAP Skills Team | [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills)
diff --git a/references/rest-odata-openapi-guide.md b/references/rest-odata-openapi-guide.md
new file mode 100644
index 0000000..e6d82b9
--- /dev/null
+++ b/references/rest-odata-openapi-guide.md
@@ -0,0 +1,2800 @@
+# REST and OData API Documentation Guide
+
+**Attribution & License**:
+- **Upstream Source**: [SAP API Style Guide](https://github.com/SAP-docs/api-style-guide)
+- **Source Commit**: main branch as of 2025-11-21
+- **Upstream License**: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) (Creative Commons Attribution 4.0 International - permits sharing and adaptation with attribution)
+- **Content Usage**: Core documentation and examples are derived from the upstream repository. Material has been consolidated from multiple files (section 30), reorganized for progressive disclosure architecture, and enhanced with additional examples and cross-references for Claude Code skill usage.
+
+**Source**: [https://github.com/SAP-docs/api-style-guide/tree/main/docs/30-rest-and-odata-api-documentation](https://github.com/SAP-docs/api-style-guide/tree/main/docs/30-rest-and-odata-api-documentation)
+
+**Last Verified**: 2025-11-21
+
+**Comprehensive Reference**: All 12 markdown files from section 30 consolidated and organized
+
+---
+
+## TABLE OF CONTENTS
+
+1. [Overview of REST and OData APIs](#overview-of-rest-and-odata-apis)
+2. [SAP API Business Hub Documentation Requirements](#sap-api-business-hub-documentation-requirements)
+3. [General Guidelines for Descriptions](#general-guidelines-for-descriptions)
+4. [Package Descriptions](#package-descriptions)
+5. [API Details (OpenAPI Info Object)](#api-details-openapi-info-object)
+6. [Operations Documentation](#operations-documentation)
+7. [Parameters Documentation](#parameters-documentation)
+8. [Responses Documentation](#responses-documentation)
+9. [Components and Definitions](#components-and-definitions)
+10. [Security Schemes](#security-schemes)
+11. [Tags](#tags)
+12. [External Documentation](#external-documentation)
+13. [Complete Examples](#complete-examples)
+14. [Best Practices Summary](#best-practices-summary)
+15. [Character Limit Reference Table](#character-limit-reference-table)
+16. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
+
+---
+
+## OVERVIEW OF REST AND OData APIs
+
+### What Are REST APIs?
+
+**REST (Representational State Transfer)** is an architectural style for building web services that enables:
+- Cross-platform CRUD (Create, Read, Update, Delete) operations over HTTP
+- Stateless client-server communication
+- Resource-oriented design using URIs
+- Standard HTTP methods (GET, POST, PUT, DELETE, PATCH)
+
+**Key Characteristics**:
+- Resources represented as URIs (e.g., `/users`, `/orders/{orderID}`)
+- Stateless interactions
+- HTTP methods define operations
+- JSON or XML as primary data formats
+- Standard HTTP status codes for responses
+
+### What Are OData APIs?
+
+**OData (Open Data Protocol)** is a RESTful web protocol for querying and updating data with:
+- Standardized query syntax for filtering, sorting, and paging
+- Consistent metadata structure
+- Support for complex operations
+- Strong typing and validation
+- Three major versions: v2.0, v3.0, v4.01
+
+**Key Characteristics**:
+- Metadata-driven architecture
+- Query language for complex data operations
+- CRUD operations over HTTP
+- Standard status codes and error handling
+- EDM (Entity Data Model) for type definitions
+
+### Documentation Approaches
+
+| Aspect | REST | OData |
+|--------|------|-------|
+| **Specification Standard** | OpenAPI 3.0.3 (Swagger) | OData Specification (OASIS) |
+| **Data Format** | JSON, XML | JSON, XML |
+| **Query Language** | Custom parameters | OData Query Language |
+| **Metadata** | OpenAPI Schema | OData EDM |
+| **Versioning** | Via URL path or header | Via URL path or OData version |
+| **Primary Use** | General-purpose APIs | Data-centric APIs |
+
+### Documentation Standards Source
+
+Both REST and OData APIs in SAP systems follow the official **SAP API Style Guide** standards:
+
+**Repository**: [https://github.com/SAP-docs/api-style-guide/tree/main/docs/30-rest-and-odata-api-documentation](https://github.com/SAP-docs/api-style-guide/tree/main/docs/30-rest-and-odata-api-documentation)
+
+**Key Files**:
+- REST/OData API Documentation Overview
+- OpenAPI Specification Guidelines
+- SAP API Business Hub Requirements
+- Naming Conventions
+
+---
+
+## SAP API BUSINESS HUB DOCUMENTATION REQUIREMENTS
+
+### What Is SAP API Business Hub?
+
+**SAP API Business Hub** ([https://api.sap.com/](https://api.sap.com/)) is the central platform for discovering, exploring, and consuming SAP APIs. It serves as the primary documentation and distribution channel for SAP's REST and OData APIs.
+
+### Hub-Specific Requirements
+
+#### Package Information
+
+Packages are the top-level organizational unit in the SAP API Business Hub.
+
+**Required Elements**:
+
+1. **Package Title**
+   - Reflects the product or product line
+   - Proper capitalization with meaningful words
+   - Include development phase if applicable: "(Alpha)", "(Beta)"
+   - Examples:
+     - "SAP SuccessFactors Employee Central"
+     - "SAP Concur Expense (Beta)"
+     - "SAP S/4HANA Cloud – Purchase Requisition API"
+
+2. **Short Description**
+   - Maximum: **250 characters** (excluding spaces)
+   - Begins with **imperative verb**: "Create", "Build", "Manage", "Configure", "Query"
+   - No period at the end
+   - Must be distinct from title and unique among packages
+   - Clear and benefit-focused language
+   - Examples:
+     - "Create, read, and update employees in the Employee Central system" (66 chars)
+     - "Manage expense reports, receipts, and reimbursements in Concur" (63 chars)
+
+3. **Overview Description**
+   - 2-3 sentences providing deeper context
+   - Addresses customers directly: "Use this package to...", "Integrate your application..."
+   - Explains what the package enables
+   - No Markdown formatting currently supported
+   - Line breaks use `\n` escape sequence
+   - Examples:
+     - "Use this package to query and manage employee data in your HR systems. The API provides comprehensive access to employee records, benefits, and organizational structures. Integration with your custom applications enables real-time HR data synchronization."
+
+4. **Target Users/Use Cases**
+   - HR: "Human Resources departments managing employee lifecycle"
+   - Finance: "Finance teams automating expense management"
+   - Integration: "Systems integrators building HR-centric solutions"
+
+### API Business Hub Metadata Fields
+
+#### In OpenAPI Specification
+
+**Supported Fields**:
+
+```yaml
+info:
+  title: "API Name"                        # max 80 chars
+  version: "1.0.0"
+  x-sap-shortText: "High-level description"  # max 180 chars
+  description: "Long description"         # 1-2 sentences
+  x-sap-stateInfo:                        # For deprecated APIs
+    state: "active|deprecated|decommissioned|beta"
+    deprecationDate: "2024-01-15"
+    successorApi: "NewAPIName"
+```
+
+**Custom Extensions**:
+- `x-sap-shortText`: Brief description for catalog display (max 180 chars)
+- `x-sap-stateInfo`: Lifecycle state information
+- `x-sap-extensible`: Flag indicating extensibility
+- `x-sap-apiType`: "REST" or "OData"
+
+### Publishing Workflow
+
+1. **Prepare Documentation**
+   - Complete OpenAPI specification with all required fields
+   - Create package metadata
+   - Write descriptions following guidelines
+
+2. **Submit to Business Hub**
+   - Package structure validated
+   - API specifications reviewed
+   - Business metadata processed
+
+3. **Quality Review**
+   - User Assistance (UA) reviews all descriptions
+   - Terminology consistency checked
+   - Documentation completeness verified
+
+4. **Publication**
+   - APIs appear in searchable catalog
+   - Documentation accessible to developers
+   - Links and examples functional
+
+---
+
+## GENERAL GUIDELINES FOR DESCRIPTIONS
+
+### Core Principles
+
+#### 1. Clarity and Conciseness
+
+**Principle**: Descriptions must be clear, precise, and free of jargon.
+
+- Use simple, direct language
+- Avoid technical acronyms unless necessary
+- Define unfamiliar terms
+- Use active voice where appropriate
+- Keep sentences relatively short
+
+**Avoid**:
+- ❌ "The ephemeral context datum manifests transient materialization paradigms"
+- ✅ "Temporary data that doesn't persist after the request"
+
+#### 2. Correct Spelling and Grammar
+
+**Requirements**:
+- Use American English spelling (e.g., "color", not "colour")
+- Check for grammar errors
+- Maintain consistent terminology across API
+- Spell out acronyms on first use: "REST (Representational State Transfer)"
+
+**Tools**:
+- Spell checkers
+- Grammar checkers (Grammarly, built-in IDE tools)
+- Consistency checkers
+
+#### 3. Formatting Standards
+
+**Capitalization**:
+- Start sentences with capital letters
+- End sentences with periods
+- Proper nouns always capitalized
+- "API", "HTTP", "REST", "OData" in all caps
+
+**Formatting Examples**:
+- ✅ "Retrieves the user profile. Maximum request timeout is 30 seconds."
+- ❌ "retrieves the user profile. maximum request timeout is 30 seconds."
+
+#### 4. Imperative vs. Descriptive Language
+
+**Imperative Form** (for operations):
+- Start with action verb in third-person singular
+- Examples: "Creates a new order", "Retrieves employee data", "Updates the configuration"
+- Avoid: "This operation creates..." or "The API creates..."
+
+**Descriptive Form** (for data types, properties):
+- Use noun phrases
+- Examples: "The unique order identifier", "User email address", "Product inventory count"
+
+### Description Length Guidelines
+
+| Element | Recommended | Maximum | Notes |
+|---------|-------------|---------|-------|
+| API Title | 50-80 chars | 80 | Should fit single line in most contexts |
+| x-sap-shortText | 100-180 chars | 180 | High-level overview for catalog |
+| Operation Summary | 50-150 chars | 255 | Appears in quick reference |
+| Operation Description | 100-300 chars | No limit | Additional context beyond summary |
+| Parameter Description | 30-100 chars | No limit | Concise explanation of purpose |
+| Response Description | 50-150 chars | No limit | Context-specific outcome description |
+| Component Description | 50-200 chars | No limit | Data structure explanation |
+
+### Common Description Patterns
+
+#### For Operations (HTTP Endpoints)
+
+**Pattern 1: Simple CRUD Operation**
+```
+Summary: "Retrieves a single user by ID"
+Description: "Fetches complete user profile information including contact details, preferences, and account status."
+```
+
+**Pattern 2: Complex Operation**
+```
+Summary: "Searches for orders with advanced filtering"
+Description: "Executes a search query returning orders matching specified criteria. Supports filtering by date range, status, customer, and amount. Results paginated with configurable page size."
+```
+
+**Pattern 3: Action/Function**
+```
+Summary: "Approves a pending document"
+Description: "Changes document status from pending to approved and notifies relevant stakeholders. Requires manager-level permissions."
+```
+
+#### For Parameters
+
+**Pattern 1: Simple Parameter**
+```
+"userId": "The unique identifier of the user"
+```
+
+**Pattern 2: Parameter with Constraints**
+```
+"pageSize": "Maximum number of results per page (minimum: 1, maximum: 100, default: 20)"
+```
+
+**Pattern 3: Optional Parameter**
+```
+"includeDetails": "If true, includes detailed breakdown; if false, returns summary only (optional, defaults to false)"
+```
+
+#### For Responses
+
+**Pattern 1: Success Response**
+```
+"200 OK": "Order successfully created. Returns the new order with assigned ID and creation timestamp."
+```
+
+**Pattern 2: Error Response - Generic**
+```
+"400 Bad Request": "Invalid request format or missing required fields. Check error details for specific violations."
+```
+
+**Pattern 3: Error Response - Context-Specific**
+```
+"409 Conflict": "Cannot process order because inventory for product is insufficient. Current stock: 5 units, requested: 10 units."
+```
+
+---
+
+## PACKAGE DESCRIPTIONS
+
+### Package-Level Documentation Structure
+
+#### Layer 1: Package Title
+
+**Purpose**: High-level identification in SAP API Business Hub catalog
+
+**Requirements**:
+- Reflects product or service line
+- Proper capitalization
+- Concise but descriptive
+- Include version or phase identifier if applicable
+
+**Examples**:
+- "SAP SuccessFactors Learning Management"
+- "SAP Concur Expense Management API (v2.1)"
+- "SAP Cloud Application Programming Model (CAP) Services"
+- "SAP S/4HANA Cloud – Materials Management (Beta)"
+
+**Prohibited Elements**:
+- ❌ "API" or "REST API" in title
+- ❌ "SAP" prefix when redundant with context
+- ❌ Technical specifications (e.g., "OpenAPI 3.0.3")
+- ❌ Version in standard semantic format alone
+
+#### Layer 2: Short Description
+
+**Purpose**: Catalog display, search results, quick overview
+
+**Specifications**:
+- Maximum: **250 characters** (not counting spaces)
+- Begins with imperative verb
+- No period at end
+- Unique across package catalog
+- Benefit-focused
+
+**Verb Selection**:
+
+| Use Case | Verbs | Examples |
+|----------|-------|----------|
+| Data Management | Create, Read, Update, Delete, Manage, Query | "Manage employee records and benefits" |
+| Integration | Integrate, Connect, Synchronize, Link | "Integrate your expense system with Cloud Concur" |
+| Configuration | Configure, Set up, Establish, Define | "Configure your HR system organization structure" |
+| Reporting | Generate, Create, Build, Report | "Generate financial reports and analysis" |
+| Process | Execute, Process, Perform, Automate | "Automate purchase order workflows" |
+
+**Examples**:
+
+```
+Package: SAP SuccessFactors Employee Central
+Short: "Create, update, and query employee records including personal information, assignments, and compensation data"
+(Chars: 119)
+
+Package: SAP Concur Travel
+Short: "Manage travel requests, bookings, and expenses with policy compliance and approval workflows"
+(Chars: 92)
+
+Package: SAP Business Technology Platform – Cloud Integration
+Short: "Build integration scenarios connecting cloud and on-premise applications with monitoring and message processing"
+(Chars: 109)
+```
+
+#### Layer 3: Overview Description
+
+**Purpose**: Detailed context for package understanding
+
+**Specifications**:
+- 2-3 sentences
+- Addresses customer audience directly
+- Explains capabilities and benefits
+- Uses `\n` for line breaks (not Markdown)
+- Provides use case context
+
+**Structure Pattern**:
+```
+Sentence 1: What the package enables
+Sentence 2: Primary capabilities and features
+Sentence 3: Key benefits or integration possibilities
+```
+
+**Example**:
+
+```
+Package: SAP Cloud Application Programming Model (CAP)
+
+Overview Description:
+"Use this package to build cloud-native applications with a streamlined development model.
+CAP provides a unified programming model for Node.js and Java, database abstraction, and built-in enterprise features like authentication and authorization.
+Integrate with SAP S/4HANA, Fiori elements, and third-party systems while maintaining productivity and scalability."
+
+(With literal \n line breaks in metadata)
+```
+
+#### Layer 4: Categorization and Keywords
+
+**Purpose**: Discoverability and searchability
+
+**Categories**:
+- Solution area (e.g., "Human Capital Management", "Finance")
+- API type (e.g., "REST", "OData")
+- Integration type (e.g., "Cloud", "On-Premise", "Hybrid")
+- Industry vertical (if applicable)
+
+**Keywords** (for internal tagging):
+- Primary domain: "Employee Management", "Expense Management", "Integration"
+- Technical tags: "REST", "OData", "JSON", "XML"
+- Use case tags: "CRUD Operations", "Query-Heavy", "Real-Time Sync"
+- Audience tags: "Enterprise", "ISV", "Integration"
+
+### Complete Package Documentation Template
+
+```yaml
+info:
+  title: "SAP [Product Name]"
+  version: "1.0.0"
+
+x-sap-package:
+  title: "SAP [Product Name]"
+  shortDescription: "[Imperative verb] [main capability] and [secondary capability]
+                    with [key feature]. (max 250 chars)"
+  overviewDescription: |
+    Use this package to [main benefit]. [Product Name] enables [primary capabilities].
+    [Integration possibilities and key advantages].
+
+  categories:
+    - solutionArea: "Human Capital Management"
+    - apiType: "REST"
+    - deploymentMode: "Cloud"
+
+  keywords:
+    - "Employee Management"
+    - "REST API"
+    - "CRUD Operations"
+    - "Real-Time Synchronization"
+```
+
+---
+
+## API DETAILS (OPENAPI INFO OBJECT)
+
+### OpenAPI Info Object Structure
+
+The `info` object in OpenAPI 3.0.3 specification defines metadata about the API itself.
+
+#### Required Fields
+
+##### 1. Title
+
+**Field**: `title`
+
+**Purpose**: Official name of the API
+
+**Specifications**:
+- Maximum: **80 characters**
+- Required field
+- Appears in documentation headers and catalog
+- Distinct from package title
+- Does not include "API" suffix (implied)
+
+**Naming Rules**:
+- Use natural language
+- Capitalize main words
+- Exclude technical specifications
+- Exclude "SAP" prefix if redundant
+- Exclude REST/OData/API type indicators
+
+**Examples**:
+
+| Good | Avoid |
+|------|-------|
+| "Employee Central" | "SAP EC API" |
+| "Purchase Order Management" | "Purchase Order REST API" |
+| "Document Approval" | "Document Approval OpenAPI 3.0.3" |
+| "Flight Search" | "Flights-Booking-API-v2" |
+| "Travel Request" | "SAP Travel Request API (REST)" |
+
+**Character Count Check**:
+```
+"Employee Central" = 17 characters (GOOD)
+"Document Management System Integration API" = 43 characters (GOOD)
+"SAP SuccessFactors Employee Central Human Resources System Integration Platform" = 78 characters (ACCEPTABLE)
+```
+
+##### 2. Version
+
+**Field**: `version`
+
+**Purpose**: API version number
+
+**Specifications**:
+- Follows semantic versioning: `MAJOR.MINOR.PATCH`
+- Examples: `1.0.0`, `2.3.1`, `1.5.0-beta`
+- Changes with API updates and breaking changes
+
+**Versioning Strategy**:
+
+| Version Change | Scenario | Update |
+|----------------|----------|--------|
+| MAJOR | Breaking changes to API contract | `1.0.0` → `2.0.0` |
+| MINOR | New functionality (backward compatible) | `1.0.0` → `1.1.0` |
+| PATCH | Bug fixes (backward compatible) | `1.0.0` → `1.0.1` |
+
+**Examples**:
+```yaml
+version: "1.0.0"        # Initial release
+version: "1.1.0"        # Added new endpoints
+version: "1.1.1"        # Fixed validation bug
+version: "2.0.0"        # Major revision with breaking changes
+```
+
+#### Optional but Highly Recommended Fields
+
+##### 3. x-sap-shortText
+
+**Field**: `x-sap-shortText`
+
+**Purpose**: High-level, concise API description for SAP API Business Hub display
+
+**Specifications**:
+- Maximum: **180 characters**
+- SAP-specific extension (custom field)
+- Appears in catalog search results
+- Distinct from overview description
+- Action-oriented language
+
+**Guidelines**:
+- Starts with strong action verb or noun phrase
+- Communicates primary use case
+- Accessible to business and technical audiences
+- No technical jargon unless universal
+
+**Examples**:
+
+```
+API: Employee Central
+x-sap-shortText: "Query and manage employee master data, assignments, and compensation information"
+(Chars: 82)
+
+API: Expense Report
+x-sap-shortText: "Create, submit, and approve employee expense reports with real-time policy validation"
+(Chars: 88)
+
+API: Travel Request
+x-sap-shortText: "Manage business travel requests and integrate with external travel reservation systems"
+(Chars: 84)
+```
+
+##### 4. Description
+
+**Field**: `description`
+
+**Purpose**: Detailed explanation of API purpose and scope
+
+**Specifications**:
+- 1-2 sentences maximum
+- Provides context beyond short text
+- Explains primary use case
+- Can reference external documentation
+- May include Markdown formatting
+
+**Writing Pattern**:
+```
+"[API Purpose]. [Primary Capabilities and Integration Points]."
+
+Example:
+"This API enables human resource management systems to query and modify employee master data.
+It provides access to personal information, organizational assignments, compensation, and benefits data with real-time synchronization."
+```
+
+**Examples**:
+
+```yaml
+description: |
+  Provides query and modification capabilities for employee
+  master data in SAP SuccessFactors. Supports synchronization
+  with external HRIS systems and talent management applications.
+
+description: |
+  Manages purchase order creation, modification, and tracking
+  for SAP S/4HANA procurement. Enables integration with supplier
+  systems and logistics providers for real-time order visibility.
+```
+
+#### Lifecycle and State Information
+
+##### 5. x-sap-stateInfo
+
+**Field**: `x-sap-stateInfo`
+
+**Purpose**: Indicates API lifecycle state (for deprecated APIs)
+
+**Structure**:
+```yaml
+x-sap-stateInfo:
+  state: "active|beta|deprecated|decommissioned"
+  deprecationDate: "YYYY-MM-DD"
+  successorApi: "NewAPIName"
+  plannedDecommissionDate: "YYYY-MM-DD"
+  moreInformation: "[https://help.sap.com/..."](https://help.sap.com/...")
+```
+
+**State Values**:
+
+| State | Meaning | Support | Timeline |
+|-------|---------|---------|----------|
+| `active` | Fully supported, production-ready | Full | Ongoing |
+| `beta` | Pre-release, may have breaking changes | Limited | Until stable release |
+| `deprecated` | Supported but will be removed | Full | Minimum 12 months |
+| `decommissioned` | No longer supported | None | Historical reference only |
+
+**Usage**:
+
+```yaml
+# Active API (default)
+x-sap-stateInfo:
+  state: "active"
+
+# Beta API
+x-sap-stateInfo:
+  state: "beta"
+  moreInformation: "[https://api.sap.com/feedback/employee-central-v2"](https://api.sap.com/feedback/employee-central-v2")
+
+# Deprecated API
+x-sap-stateInfo:
+  state: "deprecated"
+  deprecationDate: "2024-01-15"
+  successorApi: "Employee Central v2"
+  plannedDecommissionDate: "2025-01-15"
+  moreInformation: "[https://help.sap.com/migration-guide"](https://help.sap.com/migration-guide")
+```
+
+#### Complete Info Object Example
+
+```yaml
+openapi: 3.0.3
+info:
+  title: "Employee Central"
+  version: "1.5.3"
+  x-sap-shortText: "Query and manage employee master data, assignments, and compensation"
+  description: |
+    This API provides comprehensive access to employee master data in
+    SAP SuccessFactors Employee Central. It enables creation, retrieval,
+    and modification of employee records with support for organizational
+    assignments, compensation details, and benefit information.
+
+  contact:
+    name: "SAP SuccessFactors Support"
+    url: "[https://help.sap.com/successfactors"](https://help.sap.com/successfactors")
+    email: "support@sap.com"
+
+  license:
+    name: "SAP Developer License"
+    url: "[https://www.sap.com/legal"](https://www.sap.com/legal")
+
+  x-sap-stateInfo:
+    state: "active"
+```
+
+---
+
+## OPERATIONS DOCUMENTATION
+
+### What Are Operations?
+
+**Operations** are HTTP methods applied to API endpoints that define specific actions:
+- **GET**: Retrieve data
+- **POST**: Create new data
+- **PUT**: Replace existing data
+- **PATCH**: Partially update data
+- **DELETE**: Remove data
+
+Each operation requires documentation explaining its purpose, parameters, and responses.
+
+### Operation-Level Documentation
+
+#### Required Elements
+
+##### 1. Operation Summary
+
+**Field**: `summary`
+
+**Purpose**: One-line description appearing in API reference view
+
+**Specifications**:
+- Maximum: **255 characters**
+- Required for all operations
+- Clear action-oriented language
+- Appears in operation list/index
+- Sufficient to understand operation alone
+
+**Guidelines**:
+- Starts with action verb (Gets, Creates, Updates, Deletes, Searches)
+- Includes primary object and action
+- Avoids repetition of path/method
+- No period at end (optional but preferred)
+- No second-person language
+
+**Examples**:
+
+```
+GET /employees/{id}
+Summary: "Retrieve a single employee by ID"
+
+POST /employees
+Summary: "Create a new employee record"
+
+PATCH /employees/{id}
+Summary: "Update specific employee fields"
+
+DELETE /employees/{id}
+Summary: "Delete an employee record"
+
+POST /employees/search
+Summary: "Search employees by multiple criteria"
+```
+
+##### 2. Operation Description
+
+**Field**: `description`
+
+**Purpose**: Supplementary details beyond summary
+
+**Specifications**:
+- Only include if additional context needed
+- 1-3 sentences maximum
+- Omit if summary sufficient
+- Markdown formatting supported
+- Provide business context or technical constraints
+
+**Guidelines**:
+- Begins with action verb (direct third-person form)
+- **Avoid**: "This operation...", "This method...", "The API..."
+- Explains special behaviors or side effects
+- Mentions business constraints or prerequisites
+- References related operations if helpful
+- Explains pagination or filtering logic (if not in parameters)
+
+**Examples**:
+
+```
+GET /employees/{id}
+Description: (omit - summary sufficient)
+
+POST /employees
+Description: "Triggers automatic workflow notifications to
+             manager and HR department. Returns 201 Created
+             with Location header pointing to new resource."
+
+PATCH /employees/{id}
+Description: "Only updates fields specified in request body.
+             Omitted fields remain unchanged. Requires manager
+             approval for salary changes."
+
+POST /employees/search
+Description: "Supports complex filtering with operators.
+             Results automatically sorted by match relevance.
+             Maximum 10,000 results per request."
+```
+
+### Operation Structure in OpenAPI
+
+```yaml
+paths:
+  /employees:
+    post:
+      summary: "Create a new employee record"
+      description: |
+        Creates a new employee in the system. Automatically
+        assigns employee ID and sends notification to HR.
+        Requires valid company and department codes.
+
+      operationId: "createEmployee"
+      tags:
+        - "Employees"
+
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Employee"
+
+      responses:
+        '201':
+          description: "Employee successfully created"
+        '400':
+          description: "Invalid employee data"
+        '409':
+          description: "Employee already exists"
+```
+
+### Different Operation Types
+
+#### Read Operations (GET)
+
+**Summary Pattern**:
+```
+"Retrieve [resource]"
+"Get [resource]"
+"List [resources]"
+"Search [resources]"
+```
+
+**Examples**:
+- "Retrieve a single employee by ID"
+- "List all open purchase orders"
+- "Search employees by name and department"
+- "Get expense report details"
+
+#### Create Operations (POST)
+
+**Summary Pattern**:
+```
+"Create [new resource]"
+"Submit [resource]"
+"Post [action]"
+```
+
+**Examples**:
+- "Create a new employee record"
+- "Submit an expense report"
+- "Post a new comment on document"
+- "Create purchase order"
+
+#### Update Operations (PUT, PATCH)
+
+**Summary Pattern**:
+```
+"Update [resource]"
+"Replace [resource]"
+"Modify [resource]"
+"Change [specific field]"
+```
+
+**Examples**:
+- "Update employee information"
+- "Replace entire purchase order"
+- "Modify employee salary"
+- "Update travel request status"
+
+#### Delete Operations (DELETE)
+
+**Summary Pattern**:
+```
+"Delete [resource]"
+"Remove [resource]"
+"Cancel [resource]"
+```
+
+**Examples**:
+- "Delete employee record"
+- "Remove purchase order"
+- "Cancel travel request"
+- "Delete document attachment"
+
+---
+
+## PARAMETERS DOCUMENTATION
+
+### Parameter Overview
+
+**Parameters** are options passed with API requests to control behavior:
+- Filtering criteria
+- Sorting preferences
+- Pagination settings
+- Authentication tokens
+- Custom headers
+- Request body content
+
+### Parameter Location Types
+
+| Location | Usage | Example |
+|----------|-------|---------|
+| **path** | Resource identifier in URL | `/employees/{employeeId}` |
+| **query** | Filter/sort parameters | `?department=HR&sort=name` |
+| **header** | Authentication/metadata | `Authorization: Bearer token` |
+| **cookie** | Session/preference data | `sessionId=abc123` |
+| **body** | Request payload (JSON/XML) | POST body with resource data |
+
+### Required Parameter Documentation
+
+For each parameter, document:
+
+#### 1. Parameter Name
+
+**Specifications**:
+- Exactly matches API specification
+- Case-sensitive
+- Clear, meaningful names
+- Follows naming conventions (camelCase for REST, PascalCase for OData)
+
+**Examples**:
+```
+✓ employeeId, firstName, departmentCode
+✗ emp_id, EmployeeID, employee-id (inconsistent with conventions)
+```
+
+#### 2. Location (in)
+
+**Field**: `in`
+
+**Values**: `path`, `query`, `header`, `cookie`, `body`
+
+**Determines**: How parameter is passed in request
+
+#### 3. Required Status
+
+**Field**: `required`
+
+**Values**: `true` or `false`
+
+**Determines**: Whether parameter must be included
+
+#### 4. Data Type
+
+**Field**: `schema.type`
+
+**Common Types**:
+- `string`: Text values
+- `integer`: Whole numbers
+- `number`: Decimal numbers
+- `boolean`: true/false values
+- `array`: Multiple values
+- `object`: Complex structures
+
+#### 5. Description
+
+**Field**: `description`
+
+**Requirements**:
+- Concise noun phrase describing purpose
+- Maximum 100 characters for brevity
+- Explains what parameter controls
+- Mentions constraints (min/max, options, defaults)
+- No ending period
+
+**Examples**:
+
+```yaml
+# Simple parameter
+parameters:
+  - name: employeeId
+    in: path
+    required: true
+    schema:
+      type: string
+    description: "The unique employee identifier"
+
+  - name: department
+    in: query
+    required: false
+    schema:
+      type: string
+    description: "Filter by department code (optional)"
+
+  - name: pageSize
+    in: query
+    required: false
+    schema:
+      type: integer
+      minimum: 1
+      maximum: 100
+      default: 20
+    description: "Number of records per page (1-100, default 20)"
+
+  - name: sortBy
+    in: query
+    required: false
+    schema:
+      type: string
+      enum: [name, date, status]
+    description: "Sort field: name, date, or status"
+```
+
+### Parameter Documentation Patterns
+
+#### Simple Parameters
+
+```yaml
+- name: "status"
+  in: "query"
+  required: false
+  schema:
+    type: "string"
+  description: "Filter by status value"
+```
+
+#### Parameters with Constraints
+
+```yaml
+- name: "pageSize"
+  in: "query"
+  required: false
+  schema:
+    type: "integer"
+    minimum: 1
+    maximum: 100
+  description: "Results per page (minimum 1, maximum 100)"
+```
+
+#### Parameters with Enumeration
+
+```yaml
+- name: "sortOrder"
+  in: "query"
+  required: false
+  schema:
+    type: "string"
+    enum: ["ascending", "descending"]
+  description: "Sort order: ascending or descending"
+```
+
+#### Optional Parameters with Defaults
+
+```yaml
+- name: "includeDetails"
+  in: "query"
+  required: false
+  schema:
+    type: "boolean"
+    default: false
+  description: "Include detailed information (defaults to false)"
+```
+
+#### Array Parameters
+
+```yaml
+- name: "departments"
+  in: "query"
+  required: false
+  schema:
+    type: "array"
+    items:
+      type: "string"
+  description: "Filter by multiple departments (comma-separated)"
+```
+
+### Documentation Quality Guidelines
+
+#### ✅ Good Parameter Descriptions
+
+```
+"The unique employee identifier"
+"Filter by status (Open, In Progress, Closed)"
+"Number of results per page (1-100, default 20)"
+"Search query string (minimum 2 characters)"
+"Include subordinate employee records (optional, defaults to false)"
+```
+
+#### ❌ Poor Parameter Descriptions
+
+```
+"ID"                                    # Too vague
+"The status"                           # Obvious, doesn't add value
+"This parameter filters results"       # Doesn't explain what it filters
+"Required to be provided"              # Type already indicates required
+"See documentation"                    # No helpful information
+```
+
+### Parameter Organization
+
+**Recommended Order in Documentation**:
+1. Path parameters (required)
+2. Query parameters (often optional filters)
+3. Header parameters
+4. Cookie parameters
+5. Body parameters (request payload)
+
+**Within Each Category**:
+- Required parameters first
+- Optional parameters after
+- Alphabetical by name within sub-category
+
+---
+
+## RESPONSES DOCUMENTATION
+
+### Response Overview
+
+**Responses** describe what the API returns for different scenarios:
+- Success codes (2xx)
+- Client errors (4xx)
+- Server errors (5xx)
+
+Each response includes status code and description of outcome.
+
+### Response Structure
+
+#### 1. HTTP Status Code
+
+**Purpose**: Indicates success or type of failure
+
+**Common Status Codes for REST APIs**:
+
+| Code | Status | Use Case |
+|------|--------|----------|
+| **2xx** | **Success** | Request processed successfully |
+| 200 | OK | GET, PATCH success; data returned |
+| 201 | Created | POST successful; new resource created |
+| 202 | Accepted | Async operation queued for processing |
+| 204 | No Content | DELETE, POST success; no body |
+| **3xx** | **Redirection** | Client action needed for completion |
+| 301 | Moved Permanently | Resource permanently moved |
+| 304 | Not Modified | Data unchanged since last request |
+| **4xx** | **Client Error** | Invalid request or missing data |
+| 400 | Bad Request | Invalid format or missing required field |
+| 401 | Unauthorized | Authentication required or invalid |
+| 403 | Forbidden | Authenticated but insufficient permission |
+| 404 | Not Found | Requested resource doesn't exist |
+| 409 | Conflict | Request conflicts with current state |
+| **5xx** | **Server Error** | Server processing failed |
+| 500 | Internal Server Error | Unexpected server error |
+| 503 | Service Unavailable | Server temporarily unavailable |
+
+#### 2. Response Description
+
+**Field**: `description`
+
+**Requirements**:
+- Required for every response code
+- Explains outcome in plain language
+- Context-specific, not generic
+- Describes returned data (if applicable)
+- Mentions implications of status
+
+**Guidelines**:
+- Begins with capital letter
+- **Avoid generic descriptions**: "No content", "Not found"
+- **Use specific descriptions**: "Product out of stock", "Employee record not found"
+- Mentions returned format (JSON, empty body)
+- Explains business context
+
+#### 3. Response Body
+
+**Field**: `content`
+
+**Includes**:
+- Media type (application/json, application/xml)
+- Schema definition
+- Example response data
+
+### Response Documentation Patterns
+
+#### Success Response (200 OK)
+
+```yaml
+responses:
+  '200':
+    description: "Employee data successfully retrieved with full profile information"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Employee"
+        example:
+          employeeId: "E12345"
+          firstName: "John"
+          lastName: "Doe"
+          department: "Engineering"
+          status: "Active"
+```
+
+#### Created Response (201 Created)
+
+```yaml
+responses:
+  '201':
+    description: "Employee successfully created. Location header contains URL to new resource"
+    headers:
+      Location:
+        description: "URL of newly created employee"
+        schema:
+          type: "string"
+          example: "/employees/E12346"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Employee"
+```
+
+#### No Content Response (204 No Content)
+
+```yaml
+responses:
+  '204':
+    description: "Employee record successfully deleted. No response body"
+```
+
+#### Async Response (202 Accepted)
+
+```yaml
+responses:
+  '202':
+    description: "Delete request accepted. Processing occurs asynchronously. Check job status via Location header"
+    headers:
+      Location:
+        description: "URL to check processing status"
+        schema:
+          type: "string"
+          example: "/jobs/job-12345"
+```
+
+#### Bad Request Response (400)
+
+```yaml
+responses:
+  '400':
+    description: "Request validation failed. Check error details for specific field violations"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Error"
+        example:
+          errorCode: "INVALID_INPUT"
+          message: "Validation failed"
+          details:
+            - field: "email"
+              issue: "Invalid email format"
+            - field: "birthDate"
+              issue: "Date must be in YYYY-MM-DD format"
+```
+
+#### Conflict Response (409)
+
+```yaml
+responses:
+  '409':
+    description: "Cannot process request because record already exists. Provide valid unique values"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Error"
+        example:
+          errorCode: "DUPLICATE_RECORD"
+          message: "Employee with email john@example.com already exists"
+          conflictingField: "email"
+          existingRecordId: "E99999"
+```
+
+#### Not Found Response (404)
+
+```yaml
+responses:
+  '404':
+    description: "Requested employee not found. Verify employee ID is correct"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Error"
+        example:
+          errorCode: "NOT_FOUND"
+          message: "No employee found with ID E99999"
+          resourceType: "Employee"
+          providedId: "E99999"
+```
+
+#### Unauthorized Response (401)
+
+```yaml
+responses:
+  '401':
+    description: "Authentication required or token expired. Provide valid Authorization header with Bearer token"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Error"
+        example:
+          errorCode: "UNAUTHORIZED"
+          message: "Bearer token is missing or invalid"
+```
+
+#### Forbidden Response (403)
+
+```yaml
+responses:
+  '403':
+    description: "Insufficient permissions to access this resource. Contact administrator for access"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Error"
+        example:
+          errorCode: "FORBIDDEN"
+          message: "You do not have permission to update employee records"
+          requiredRole: "HR_Manager"
+          yourRole: "HR_User"
+```
+
+### Response Documentation Best Practices
+
+#### ✅ Effective Response Descriptions
+
+```
+"Employee successfully created with assigned ID. Location header contains URL to new resource."
+"Product is out of stock. Check available inventory levels in the system."
+"Invalid request format. Email field must be in user@example.com format."
+"Insufficient permissions. Only managers can approve documents. Contact HR for role assignment."
+"Order cannot be modified because it's already been shipped. Contact customer service for options."
+```
+
+#### ❌ Poor Response Descriptions
+
+```
+"OK"                                              # Too generic
+"No content"                                      # Doesn't explain context
+"Bad request"                                     # Doesn't explain what's bad
+"Not found"                                       # Doesn't explain what wasn't found
+"Error"                                           # No helpful information
+"See error details"                               # Doesn't describe status code
+```
+
+### Response Error Handling
+
+#### Standard Error Response Schema
+
+```yaml
+components:
+  schemas:
+    Error:
+      type: object
+      required:
+        - errorCode
+        - message
+      properties:
+        errorCode:
+          type: string
+          description: "Machine-readable error code for programmatic handling"
+          example: "INVALID_INPUT"
+        message:
+          type: string
+          description: "Human-readable error message"
+          example: "Email field is required and must be valid"
+        details:
+          type: array
+          description: "Detailed information about each error"
+          items:
+            type: object
+            properties:
+              field:
+                type: string
+                description: "Field that caused the error"
+              issue:
+                type: string
+                description: "Specific problem with the field"
+        timestamp:
+          type: string
+          format: date-time
+          description: "When error occurred"
+```
+
+#### Error Response Documentation Template
+
+```yaml
+responses:
+  '400':
+    description: "[Brief status]. [Explanation of what went wrong]. [How to fix]"
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/Error"
+        example:
+          errorCode: "[SPECIFIC_CODE]"
+          message: "[Context-specific message]"
+          details: [...]
+```
+
+---
+
+## COMPONENTS AND DEFINITIONS
+
+### What Are Components?
+
+**Components** (in OpenAPI 3.0) define reusable data structures:
+- Request/response body schemas
+- Parameter definitions
+- Response headers
+- Security schemes
+- Examples
+
+Also called **Definitions** in OpenAPI 2.0 (Swagger).
+
+### Schema Documentation
+
+#### Schema Object Structure
+
+```yaml
+components:
+  schemas:
+    Employee:
+      type: object
+      required:
+        - employeeId
+        - firstName
+        - lastName
+      properties:
+        employeeId:
+          type: string
+          description: "Unique employee identifier assigned by system"
+          example: "E12345"
+
+        firstName:
+          type: string
+          description: "Employee's first name"
+          minLength: 1
+          maxLength: 50
+          example: "John"
+
+        lastName:
+          type: string
+          description: "Employee's last name"
+          minLength: 1
+          maxLength: 50
+          example: "Doe"
+
+        emailAddress:
+          type: string
+          format: email
+          description: "Corporate email address (must be unique)"
+          example: "john.doe@company.com"
+
+        department:
+          type: string
+          enum: ["Engineering", "Sales", "HR", "Finance"]
+          description: "Department assignment. Valid values: Engineering, Sales, HR, Finance"
+          example: "Engineering"
+
+        salary:
+          type: number
+          format: double
+          description: "Annual salary in USD (minimum $20,000)"
+          minimum: 20000
+          example: 85000.00
+
+        isActive:
+          type: boolean
+          description: "Whether employee is currently active (true) or inactive (false)"
+          default: true
+          example: true
+```
+
+#### Component Description Guidelines
+
+**For Objects (Complex Types)**:
+- Brief description of what the object represents
+- Explain primary purpose
+- Mention key characteristics
+
+**For Properties (Fields)**:
+- Concise description of property meaning
+- Explain constraints (min/max, format, allowed values)
+- Provide example value
+- Mention relationships to other fields
+
+**Naming Conventions**:
+
+| Schema Type | Naming | Examples |
+|-------------|--------|----------|
+| **Request Body** | Use operation-specific name | `CreateEmployeeRequest`, `UpdateEmployeeRequest` |
+| **Response Body** | Use resource name | `Employee`, `Order`, `Document` |
+| **Collection** | Plural form | `Employees`, `Orders`, `Documents` |
+| **Error** | Error-specific name | `ValidationError`, `NotFoundError` |
+
+#### Complete Schema Example
+
+```yaml
+Employee:
+  type: object
+  description: "Represents an employee in the system with personal and professional information"
+  required:
+    - employeeId
+    - firstName
+    - lastName
+    - email
+    - department
+  properties:
+    employeeId:
+      type: string
+      description: "System-assigned unique identifier"
+      pattern: "^E[0-9]{5}$"
+      example: "E12345"
+
+    firstName:
+      type: string
+      description: "Employee's first name"
+      minLength: 1
+      maxLength: 50
+      example: "John"
+
+    lastName:
+      type: string
+      description: "Employee's surname"
+      minLength: 1
+      maxLength: 50
+      example: "Doe"
+
+    email:
+      type: string
+      format: email
+      description: "Unique corporate email address"
+      example: "john.doe@company.com"
+
+    dateOfBirth:
+      type: string
+      format: date
+      description: "Birth date in YYYY-MM-DD format (optional)"
+      example: "1985-03-15"
+
+    department:
+      type: string
+      enum: ["Engineering", "Sales", "HR", "Finance"]
+      description: "Department assignment"
+      example: "Engineering"
+
+    manager:
+      type: object
+      description: "Reference to manager (optional)"
+      properties:
+        managerId:
+          type: string
+          description: "Manager's employee ID"
+          example: "E10001"
+        managerName:
+          type: string
+          description: "Manager's full name"
+          example: "Jane Smith"
+
+    joinDate:
+      type: string
+      format: date
+      description: "Date employee joined company"
+      example: "2020-06-01"
+
+    isActive:
+      type: boolean
+      description: "Active employment status"
+      default: true
+      example: true
+
+    tags:
+      type: array
+      description: "Custom tags for employee classification"
+      items:
+        type: string
+      example: ["key-employee", "retention-focus"]
+```
+
+### Component Usage Documentation
+
+#### Referenced in Requests
+
+```yaml
+paths:
+  /employees:
+    post:
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateEmployeeRequest"
+```
+
+#### Referenced in Responses
+
+```yaml
+paths:
+  /employees/{employeeId}:
+    get:
+      responses:
+        '200':
+          description: "Employee data successfully retrieved"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Employee"
+```
+
+#### Referenced in Parameters
+
+```yaml
+parameters:
+  - name: filter
+    in: query
+    description: "Filter expression using employee properties"
+    schema:
+      $ref: "#/components/schemas/EmployeeFilter"
+```
+
+### Enum Documentation
+
+```yaml
+components:
+  schemas:
+    EmployeeStatus:
+      type: string
+      enum:
+        - Active
+        - Inactive
+        - OnLeave
+        - Terminated
+      description: "Employment status. Valid values: Active (currently employed), Inactive (on leave without pay), OnLeave (paid leave), Terminated (employment ended)"
+```
+
+---
+
+## SECURITY SCHEMES
+
+### What Are Security Schemes?
+
+**Security Schemes** define how APIs authenticate requests:
+- Bearer tokens (OAuth 2.0)
+- API keys
+- Basic authentication
+- OpenID Connect
+
+### Common SAP API Security Schemes
+
+#### 1. OAuth 2.0 Bearer Token
+
+**Use Case**: Cloud applications, third-party integrations
+
+**Flow Type**: Client Credentials, Authorization Code, etc.
+
+**Documentation**:
+
+```yaml
+components:
+  securitySchemes:
+    OAuth2ClientCredentials:
+      type: oauth2
+      description: "OAuth 2.0 Client Credentials flow for server-to-server authentication"
+      flows:
+        clientCredentials:
+          tokenUrl: "[https://auth.sap.com/oauth/token"](https://auth.sap.com/oauth/token")
+          refreshUrl: "[https://auth.sap.com/oauth/refresh"](https://auth.sap.com/oauth/refresh")
+          scopes:
+            "employees:read": "Read employee data"
+            "employees:write": "Create/modify employee data"
+            "employees:delete": "Delete employee records"
+```
+
+#### 2. API Key Authentication
+
+**Use Case**: Simple API access, testing
+
+**Documentation**:
+
+```yaml
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: "API key authentication for direct API access. Obtain key from SAP API Business Hub"
+```
+
+#### 3. Basic Authentication
+
+**Use Case**: Legacy systems, simple auth
+
+**Documentation**:
+
+```yaml
+components:
+  securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic
+      description: "HTTP Basic authentication using username:password encoded in Authorization header"
+```
+
+#### 4. OpenID Connect
+
+**Use Case**: Enterprise single sign-on
+
+**Documentation**:
+
+```yaml
+components:
+  securitySchemes:
+    OpenIDConnect:
+      type: openIdConnect
+      openIdConnectUrl: "[https://auth.sap.com/.well-known/openid-configuration"](https://auth.sap.com/.well-known/openid-configuration")
+      description: "OpenID Connect authentication for enterprise environments"
+```
+
+### Security Scheme Application
+
+#### Apply to All Operations
+
+```yaml
+security:
+  - OAuth2ClientCredentials:
+      - "employees:read"
+      - "employees:write"
+```
+
+#### Apply to Specific Operations
+
+```yaml
+paths:
+  /employees:
+    get:
+      security:
+        - OAuth2ClientCredentials:
+            - "employees:read"
+      # ...
+
+    post:
+      security:
+        - OAuth2ClientCredentials:
+            - "employees:write"
+      # ...
+```
+
+### Security Documentation Best Practices
+
+#### ✅ Good Security Documentation
+
+```
+"OAuth 2.0 Client Credentials flow for server-to-server authentication.
+Obtain access token from [https://auth.sap.com/oauth/token](https://auth.sap.com/oauth/token) using your client credentials.
+Include token in Authorization header: Authorization: Bearer "
+```
+
+#### ❌ Poor Security Documentation
+
+```
+"OAuth 2.0"                          # Too vague
+"Use authentication"                 # No details
+"See SAP documentation"              # No specifics
+```
+
+---
+
+## TAGS
+
+### What Are Tags?
+
+**Tags** are labels that group related operations for organization in documentation:
+- Organize operations by resource type
+- Create documentation structure
+- Improve API navigation
+
+### Tag Definition and Usage
+
+#### Tag Object Structure
+
+```yaml
+tags:
+  - name: "Employees"
+    description: "Operations for managing employee records including creation, retrieval, updates, and deletions"
+    externalDocs:
+      description: "Employee Management Guide"
+      url: "[https://help.sap.com/employees"](https://help.sap.com/employees")
+
+  - name: "Departments"
+    description: "Operations for querying and managing department structures and assignments"
+    externalDocs:
+      description: "Organization Guide"
+      url: "[https://help.sap.com/departments"](https://help.sap.com/departments")
+
+  - name: "Compensation"
+    description: "Operations for managing salary, benefits, and compensation-related data"
+```
+
+#### Applying Tags to Operations
+
+```yaml
+paths:
+  /employees:
+    post:
+      tags:
+        - "Employees"
+      summary: "Create a new employee"
+      # ...
+
+  /employees/{employeeId}:
+    get:
+      tags:
+        - "Employees"
+      summary: "Retrieve employee details"
+      # ...
+
+    patch:
+      tags:
+        - "Employees"
+      summary: "Update employee information"
+      # ...
+
+  /employees/{employeeId}/compensation:
+    get:
+      tags:
+        - "Compensation"
+      summary: "Get employee compensation details"
+      # ...
+```
+
+### Tag Documentation Guidelines
+
+#### Tag Name
+
+**Requirements**:
+- Clear, noun-based names (not verbs)
+- Follows resource/domain structure
+- Singular or plural consistently
+- Capitalized properly
+
+**Examples**:
+
+```
+✓ "Employees", "Orders", "Travel Requests", "Expenses"
+✗ "Create Employee", "Get Orders", "employee management"
+```
+
+#### Tag Description
+
+**Requirements**:
+- 1-2 sentences explaining tag's scope
+- Explains what operations it contains
+- Lists related operations or domains
+- Provides context for developers
+
+**Examples**:
+
+```
+"Operations for managing employee records including personal information, assignments, and employment status"
+
+"CRUD operations for purchase orders including creation, approval workflows, and fulfillment tracking"
+
+"Query and manage organizational structure, department hierarchies, and cost center allocations"
+```
+
+### Tag Organization Patterns
+
+#### Pattern 1: Resource-Based Tags
+
+```yaml
+tags:
+  - name: "Employees"
+  - name: "Departments"
+  - name: "Compensation"
+  - name: "Benefits"
+```
+
+#### Pattern 2: Domain-Based Tags
+
+```yaml
+tags:
+  - name: "Human Resources"
+  - name: "Procurement"
+  - name: "Finance"
+  - name: "Supply Chain"
+```
+
+#### Pattern 3: Operation-Based Tags
+
+```yaml
+tags:
+  - name: "Read Operations"
+  - name: "Write Operations"
+  - name: "Administrative Operations"
+```
+
+---
+
+## EXTERNAL DOCUMENTATION
+
+### What Is External Documentation?
+
+**External Documentation** links from API specification to:
+- General guides and tutorials
+- Use case documentation
+- API governance policies
+- Related documentation resources
+
+### Two Levels of External Documentation
+
+#### 1. Top-Level External Documentation
+
+**Scope**: Entire API
+
+**Location**: OpenAPI root level
+
+```yaml
+externalDocs:
+  description: "Complete API documentation and guides"
+  url: "[https://help.sap.com/employee-central"](https://help.sap.com/employee-central")
+```
+
+#### 2. Operation-Level External Documentation
+
+**Scope**: Individual operations
+
+**Location**: Per-operation specification
+
+```yaml
+paths:
+  /employees:
+    post:
+      externalDocs:
+        description: "Step-by-step guide to onboarding new employees"
+        url: "[https://help.sap.com/guides/employee-onboarding"](https://help.sap.com/guides/employee-onboarding")
+```
+
+### External Documentation Best Practices
+
+#### ✅ Effective Links
+
+```
+Description: "Employee creation workflow"
+URL: "[https://help.sap.com/employee-central/guide/create-employee"](https://help.sap.com/employee-central/guide/create-employee")
+
+Description: "API rate limiting and quotas"
+URL: "[https://help.sap.com/employee-central/guide/rate-limits"](https://help.sap.com/employee-central/guide/rate-limits")
+
+Description: "Error codes and troubleshooting"
+URL: "[https://help.sap.com/employee-central/guide/errors"](https://help.sap.com/employee-central/guide/errors")
+```
+
+#### ❌ Poor Links
+
+```
+Description: "Documentation"                          # Too vague
+URL: "[https://help.sap.com"](https://help.sap.com")                          # Root-level, not specific
+
+Description: "Click here"                             # Not descriptive
+URL: "[https://help.sap.com/some-page"](https://help.sap.com/some-page")               # No context
+
+Description: "Employee API"                           # Obvious
+URL: "[https://help.sap.com/different-product"](https://help.sap.com/different-product")       # Wrong product
+```
+
+### Common External Documentation Topics
+
+| Topic | When to Link | Example URL |
+|-------|--------------|-------------|
+| **Getting Started** | Root API level | `/guides/getting-started` |
+| **Authentication** | Security schemes section | `/guides/authentication` |
+| **Rate Limiting** | Root API level | `/guides/rate-limits` |
+| **Error Handling** | Error responses | `/guides/error-codes` |
+| **Use Cases** | Related operation groups | `/guides/use-cases/payroll` |
+| **Data Mapping** | Complex schemas | `/guides/field-mapping` |
+| **Migration Guide** | Deprecated APIs | `/guides/migration-v1-to-v2` |
+
+---
+
+## COMPLETE EXAMPLES
+
+### Example 1: Simple REST API - Employee Management
+
+```yaml
+openapi: 3.0.3
+
+info:
+  title: "Employee Central"
+  version: "1.0.0"
+  x-sap-shortText: "Create, retrieve, and manage employee records with assignment and compensation data"
+  description: |
+    This API provides comprehensive access to employee master data in SAP SuccessFactors.
+    Enables creation, retrieval, and modification of employee records with support for
+    organizational assignments and compensation information.
+
+  contact:
+    name: "SAP Support"
+    url: "[https://help.sap.com"](https://help.sap.com")
+
+externalDocs:
+  description: "Employee Central Guide"
+  url: "[https://help.sap.com/employee-central"](https://help.sap.com/employee-central")
+
+servers:
+  - url: "[https://api.sap.com/employeecentral"](https://api.sap.com/employeecentral")
+    description: "Production environment"
+
+components:
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: "[https://auth.sap.com/oauth/token"](https://auth.sap.com/oauth/token")
+          scopes:
+            "employees:read": "Read employee data"
+            "employees:write": "Create/modify employee data"
+
+  schemas:
+    Employee:
+      type: object
+      description: "Employee master data record"
+      required:
+        - employeeId
+        - firstName
+        - lastName
+        - email
+      properties:
+        employeeId:
+          type: string
+          description: "System-assigned unique employee identifier"
+          example: "E12345"
+        firstName:
+          type: string
+          description: "First name"
+          minLength: 1
+          maxLength: 50
+          example: "John"
+        lastName:
+          type: string
+          description: "Last name"
+          minLength: 1
+          maxLength: 50
+          example: "Doe"
+        email:
+          type: string
+          format: email
+          description: "Corporate email address"
+          example: "john.doe@company.com"
+        department:
+          type: string
+          description: "Department assignment"
+          example: "Engineering"
+        hireDate:
+          type: string
+          format: date
+          description: "Date employee joined company"
+          example: "2020-06-01"
+
+    Error:
+      type: object
+      required:
+        - errorCode
+        - message
+      properties:
+        errorCode:
+          type: string
+          description: "Error code identifier"
+        message:
+          type: string
+          description: "Error description"
+
+security:
+  - OAuth2:
+      - "employees:read"
+      - "employees:write"
+
+tags:
+  - name: "Employees"
+    description: "Operations for managing employee records"
+
+paths:
+  /employees:
+    get:
+      tags:
+        - "Employees"
+      summary: "List all employees"
+      description: "Retrieves all employees with optional filtering and pagination"
+      parameters:
+        - name: department
+          in: query
+          description: "Filter by department"
+          schema:
+            type: string
+        - name: pageSize
+          in: query
+          description: "Number of results per page (default 20)"
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: "Successfully retrieved employee list"
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Employee"
+        '401':
+          description: "Authentication required"
+        '500':
+          description: "Server error"
+
+    post:
+      tags:
+        - "Employees"
+      summary: "Create new employee"
+      description: "Creates a new employee record. Automatically assigns employee ID and sends notifications"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Employee"
+      responses:
+        '201':
+          description: "Employee successfully created"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Employee"
+        '400':
+          description: "Invalid employee data"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        '409':
+          description: "Employee already exists with provided email"
+
+  /employees/{employeeId}:
+    get:
+      tags:
+        - "Employees"
+      summary: "Retrieve employee by ID"
+      description: "Fetches complete employee record including all assignments and compensation details"
+      parameters:
+        - name: employeeId
+          in: path
+          required: true
+          description: "Employee ID"
+          schema:
+            type: string
+      responses:
+        '200':
+          description: "Employee details retrieved successfully"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Employee"
+        '404':
+          description: "Employee not found"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+    patch:
+      tags:
+        - "Employees"
+      summary: "Update employee information"
+      description: "Modifies employee record. Only specified fields are updated. Requires manager approval for salary changes"
+      parameters:
+        - name: employeeId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Employee"
+      responses:
+        '200':
+          description: "Employee successfully updated"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Employee"
+        '404':
+          description: "Employee not found"
+
+    delete:
+      tags:
+        - "Employees"
+      summary: "Delete employee record"
+      description: "Removes employee from system. Marks as inactive rather than physical deletion"
+      parameters:
+        - name: employeeId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: "Employee successfully deleted"
+        '404':
+          description: "Employee not found"
+```
+
+### Example 2: OData API - Purchase Orders
+
+```yaml
+openapi: 3.0.3
+
+info:
+  title: "Purchase Orders"
+  version: "1.0.0"
+  x-sap-shortText: "Query and manage purchase orders with approval workflows and supplier integration"
+  description: |
+    OData API providing access to purchase order data in SAP S/4HANA.
+    Enables querying, creating, and modifying purchase orders with real-time
+    approval tracking and supplier status management.
+  x-sap-apiType: "OData"
+
+externalDocs:
+  description: "Purchase Order Documentation"
+  url: "[https://help.sap.com/purchase-orders"](https://help.sap.com/purchase-orders")
+
+servers:
+  - url: "[https://api.sap.com/s4hana/odata/v4/purchaseorders"](https://api.sap.com/s4hana/odata/v4/purchaseorders")
+    description: "S/4HANA OData v4 endpoint"
+
+components:
+  securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic
+      description: "HTTP Basic authentication"
+
+  schemas:
+    PurchaseOrder:
+      type: object
+      description: "Purchase order document"
+      properties:
+        ID:
+          type: string
+          description: "Purchase order unique identifier"
+        PurchaseOrderNumber:
+          type: string
+          description: "Human-readable PO number"
+        SupplierName:
+          type: string
+          description: "Name of supplying vendor"
+        OrderDate:
+          type: string
+          format: date
+          description: "Date PO was created"
+        Amount:
+          type: number
+          description: "Total PO amount in local currency"
+        Status:
+          type: string
+          enum: ["Draft", "Submitted", "Approved", "Rejected", "Received"]
+          description: "Current PO status in approval workflow"
+        Items:
+          type: array
+          description: "Individual line items"
+          items:
+            type: object
+            properties:
+              LineNumber:
+                type: string
+              Material:
+                type: string
+              Quantity:
+                type: number
+              UnitPrice:
+                type: number
+
+security:
+  - BasicAuth: []
+
+paths:
+  /PurchaseOrders:
+    get:
+      summary: "Query purchase orders"
+      description: "Retrieves purchase orders with OData filtering and paging. Supports $filter, $orderby, $top, $skip"
+      parameters:
+        - name: "$filter"
+          in: query
+          description: "OData filter expression (e.g., Status eq 'Approved')"
+          schema:
+            type: string
+        - name: "$orderby"
+          in: query
+          description: "OData orderby expression (e.g., OrderDate desc)"
+          schema:
+            type: string
+        - name: "$top"
+          in: query
+          description: "Number of records to return (maximum 1000)"
+          schema:
+            type: integer
+        - name: "$skip"
+          in: query
+          description: "Number of records to skip for pagination"
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: "Successfully retrieved purchase orders"
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  value:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/PurchaseOrder"
+
+    post:
+      summary: "Create purchase order"
+      description: "Creates new purchase order. Validates supplier and material masters. Triggers initial approval workflow"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PurchaseOrder"
+      responses:
+        '201':
+          description: "Purchase order created successfully"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PurchaseOrder"
+        '400':
+          description: "Invalid PO data or missing required fields"
+
+  /PurchaseOrders('{ID}'):
+    get:
+      summary: "Get purchase order details"
+      description: "Retrieves complete purchase order with all line items and approval history"
+      parameters:
+        - name: ID
+          in: path
+          required: true
+          description: "Purchase order ID"
+          schema:
+            type: string
+      responses:
+        '200':
+          description: "Purchase order details"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PurchaseOrder"
+```
+
+---
+
+## BEST PRACTICES SUMMARY
+
+### Documentation Quality Principles
+
+#### 1. Clarity First
+
+- Write descriptions for developers without API context
+- Use simple, direct language
+- Define technical terms
+- Provide practical examples
+
+#### 2. Completeness
+
+- Document every operation, parameter, and response
+- Include all status codes (success and error)
+- Explain what data is returned
+- Describe error scenarios
+
+#### 3. Consistency
+
+- Use consistent terminology across API
+- Follow naming conventions strictly
+- Maintain uniform description style
+- Organize information predictably
+
+#### 4. Context-Specificity
+
+- Avoid generic error descriptions
+- Explain business context
+- Describe constraints and limitations
+- Mention prerequisites or requirements
+
+#### 5. Usability
+
+- Organize information logically
+- Group related operations with tags
+- Cross-reference related endpoints
+- Provide practical examples
+
+### Writing Quality Checklist
+
+Before publishing API documentation, verify:
+
+- [ ] Every operation has meaningful summary (max 255 chars)
+- [ ] Operation descriptions provide supplementary context
+- [ ] All parameters documented with clear descriptions
+- [ ] Every status code explained with context-specific description
+- [ ] Success responses show data structure and example
+- [ ] Error responses explain what went wrong and how to fix
+- [ ] API title clear and follows naming rules (max 80 chars)
+- [ ] x-sap-shortText compelling and benefit-focused (max 180 chars)
+- [ ] Package descriptions use imperative verbs
+- [ ] All schemas documented with descriptions
+- [ ] Security requirements clearly stated
+- [ ] Tags organized logically with descriptions
+- [ ] External links functional and relevant
+- [ ] Spelling and grammar correct (American English)
+- [ ] No sensitive data in examples
+- [ ] Terminology consistent throughout
+- [ ] Complex concepts explained simply
+
+---
+
+## CHARACTER LIMIT REFERENCE TABLE
+
+### Quick Reference: Character Limits for All API Elements
+
+| Element | Max Chars | Notes | Example |
+|---------|-----------|-------|---------|
+| **API Title** | 80 | OpenAPI info.title | "Employee Central" (17 chars) |
+| **x-sap-shortText** | 180 | SAP-specific high-level description | "Create, update, and query..." (82 chars) |
+| **Operation Summary** | 255 | Appears in operation list | "Retrieve employee by ID" (23 chars) |
+| **Package Title** | No strict limit | Catalog display | "SAP SuccessFactors..." |
+| **Package Short Desc** | 250 | Not counting spaces | Typical 60-120 chars |
+| **Parameter Name** | Language dependent | Matches spec | "employeeId" |
+| **Parameter Desc** | No strict limit | Recommended 30-100 | "Employee unique identifier" |
+| **Property Desc** | No strict limit | Recommended 30-80 | "User email address" |
+| **Error Description** | No strict limit | Recommended 50-150 | "Cannot process order..." |
+| **Enum Value Desc** | No strict limit | Recommended 30-80 | "Active employment status" |
+
+### Practical Counting Examples
+
+**For Package Short Description (max 250 chars, not counting spaces)**:
+
+```
+Original: "Create, update, and query employee records including personal
+           information, organizational assignments, and compensation data"
+
+Count (no spaces): Create,update,andqueryemployeerecordsincludingpersonal...
+Character count: 119 ✓ (GOOD - well under 250)
+```
+
+**For x-sap-shortText (max 180 chars)**:
+
+```
+Original: "Query and manage employee master data, assignments, and
+           compensation information with real-time synchronization"
+
+Count: 118 characters ✓ (GOOD - under 180 limit)
+```
+
+**For Operation Summary (max 255 chars)**:
+
+```
+Original: "Searches for matching orders with advanced filtering by date,
+           status, and amount with results pagination"
+
+Count: 118 characters ✓ (GOOD - under 255 limit)
+```
+
+---
+
+## ANTI-PATTERNS TO AVOID
+
+### Naming Anti-Patterns
+
+#### ❌ Including Technical Specifics
+
+```
+"SAP Employee Central REST API v2.0"
+```
+
+**Problem**: Technical specifications shouldn't be in name
+**Fix**: "Employee Central"
+
+#### ❌ Using API Type in Name
+
+```
+"Purchase Order OData Service"
+```
+
+**Problem**: API type is implicit
+**Fix**: "Purchase Orders"
+
+#### ❌ Starting with SAP Prefix
+
+```
+"SAP Human Resources Employee Management"
+```
+
+**Problem**: Redundant context
+**Fix**: "Employee Management" (in HR context)
+
+#### ❌ Using Verbs Instead of Nouns
+
+```
+"Managing Employee Data"
+```
+
+**Problem**: Not a clear entity name
+**Fix**: "Employee Data" or "Employee Management"
+
+---
+
+### Description Anti-Patterns
+
+#### ❌ Second-Person Language
+
+```
+❌ "You can create a new employee"
+✅ "Creates a new employee"
+
+❌ "You need to provide the employee ID"
+✅ "Requires employee ID in path parameter"
+```
+
+#### ❌ Repeating Summary Information
+
+```
+Operation Summary: "Creates a new order"
+
+❌ Description: "This operation creates a new order in the system"
+✅ Description: "Automatically assigns order number and sends confirmation to customer"
+```
+
+#### ❌ Generic Error Descriptions
+
+```
+❌ "Bad Request"
+❌ "Not Found"
+❌ "Server Error"
+
+✅ "Email field must be in user@example.com format"
+✅ "No employee found with ID E99999"
+✅ "Database temporarily unavailable. Try again in 60 seconds"
+```
+
+#### ❌ Including Implementation Details
+
+```
+❌ "Calls internal service to validate employee"
+✅ "Validates employee against company records"
+
+❌ "Queries three database tables and joins results"
+✅ "Retrieves complete employee profile with all departments"
+```
+
+#### ❌ Vague Language
+
+```
+❌ "Handles employee information"
+✅ "Creates, updates, and deletes employee records"
+
+❌ "Returns data"
+✅ "Returns array of employees matching search criteria"
+
+❌ "May fail in some cases"
+✅ "Returns 409 Conflict if employee email already exists"
+```
+
+---
+
+### Parameter Documentation Anti-Patterns
+
+#### ❌ Obvious Descriptions
+
+```
+❌ "The employeeId"
+❌ "The status field"
+❌ "Required parameter"
+
+✅ "The unique employee identifier"
+✅ "Employment status (Active, Inactive, OnLeave)"
+✅ "Employee ID required in URL path"
+```
+
+#### ❌ Missing Constraints
+
+```
+❌ "Number of results per page"
+✅ "Number of results per page (minimum 1, maximum 100, default 20)"
+
+❌ "Search query"
+✅ "Search query (minimum 2 characters, case-insensitive)"
+
+❌ "Filter value"
+✅ "Filter by status (valid values: Open, Closed, Pending)"
+```
+
+#### ❌ Inconsistent Formatting
+
+```
+❌ Parameter 1: "The employee identifier"
+❌ Parameter 2: "department code"
+❌ Parameter 3: "Is Active Status"
+
+✅ Parameter 1: "Employee unique identifier"
+✅ Parameter 2: "Department code"
+✅ Parameter 3: "Active employee status (true/false)"
+```
+
+---
+
+### Response Documentation Anti-Patterns
+
+#### ❌ No Context
+
+```
+❌ "OK"
+❌ "Created"
+❌ "Bad Request"
+
+✅ "Employee successfully created. Location header contains URL to new resource"
+✅ "Employee record not found. Verify employee ID is correct"
+✅ "Email field must be valid format (user@example.com)"
+```
+
+#### ❌ Missing Error Explanation
+
+```
+❌ 400 Bad Request: "Bad request"
+✅ 400 Bad Request: "Invalid request format. Email must be in user@example.com format"
+
+❌ 404 Not Found: "Not found"
+✅ 404 Not Found: "No employee found with ID E99999"
+
+❌ 409 Conflict: "Conflict"
+✅ 409 Conflict: "Cannot process because inventory insufficient. Available: 5 units, Requested: 10 units"
+```
+
+#### ❌ Inconsistent Response Structure
+
+```
+❌ Some 201 responses show created resource
+❌ Some 201 responses show empty body
+
+✅ Consistent structure across all creation endpoints
+✅ Document what's returned in each case
+```
+
+---
+
+### Schema Documentation Anti-Patterns
+
+#### ❌ Missing Property Descriptions
+
+```
+❌ properties:
+    employeeId: {}
+    name: {}
+    email: {}
+
+✅ properties:
+    employeeId:
+      description: "System-assigned unique identifier"
+    name:
+      description: "Employee full name"
+    email:
+      description: "Corporate email address"
+```
+
+#### ❌ Not Explaining Constraints
+
+```
+❌ salary:
+    type: number
+
+✅ salary:
+    type: number
+    description: "Annual salary in USD"
+    minimum: 20000
+    example: 85000.00
+```
+
+#### ❌ Unclear Enum Values
+
+```
+❌ status:
+    enum: ["A", "I", "L"]
+
+✅ status:
+    enum: ["Active", "Inactive", "OnLeave"]
+    description: "Employee status. Active = currently employed, Inactive = no longer employed, OnLeave = temporary leave"
+```
+
+---
+
+### Organization Anti-Patterns
+
+#### ❌ Inconsistent Tag Usage
+
+```
+❌ Operation 1: tags: ["Employees"]
+❌ Operation 2: tags: ["Employee"]
+❌ Operation 3: tags: ["Employee Management"]
+
+✅ All operations consistently use: ["Employees"]
+```
+
+#### ❌ Missing Related Links
+
+```
+❌ No cross-references between related operations
+✅ Link GET to POST, PUT, DELETE for same resource
+
+❌ Orphaned operations with no tag
+✅ Every operation tagged for organization
+```
+
+#### ❌ Poor External Documentation
+
+```
+❌ externalDocs:
+    description: "Documentation"
+    url: "[https://help.sap.com"](https://help.sap.com")
+
+✅ externalDocs:
+    description: "Employee onboarding workflow guide"
+    url: "[https://help.sap.com/guides/employee-onboarding"](https://help.sap.com/guides/employee-onboarding")
+```
+
+---
+
+### Security Anti-Patterns
+
+#### ❌ Unclear Security Requirements
+
+```
+❌ No security schemes defined
+
+✅ Clear OAuth 2.0 configuration with token URL and scopes
+
+❌ Security scheme documented but not applied to operations
+
+✅ Security applied to all operations and documented
+```
+
+#### ❌ Generic Scope Names
+
+```
+❌ scopes:
+    "api": "API access"
+    "read": "Read access"
+
+✅ scopes:
+    "employees:read": "Read employee data"
+    "employees:write": "Create and modify employee data"
+    "employees:delete": "Delete employee records"
+```
+
+---
+
+### Example Anti-Patterns
+
+#### ❌ Unrealistic Examples
+
+```
+❌ Example with fake/obvious data that doesn't match real API
+❌ Example missing required fields
+❌ Example with incorrect data types
+
+✅ Real-world example with all required fields
+✅ Data types match schema definition
+✅ Values realistic and properly formatted
+```
+
+#### ❌ Missing Examples
+
+```
+❌ No request body example for POST operation
+❌ No error response example
+❌ No filtering/pagination example
+
+✅ Complete request and response examples
+✅ Show both success and error scenarios
+✅ Demonstrate complex features
+```
+
+---
+
+## REFERENCES & OFFICIAL STANDARDS
+
+**Official SAP API Style Guide Section 30**:
+[https://github.com/SAP-docs/api-style-guide/tree/main/docs/30-rest-and-odata-api-documentation](https://github.com/SAP-docs/api-style-guide/tree/main/docs/30-rest-and-odata-api-documentation)
+
+**OpenAPI Specification**:
+[https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html)
+
+**OData Specification**:
+[https://www.odata.org/documentation/](https://www.odata.org/documentation/)
+
+**SAP API Business Hub**:
+[https://api.sap.com/](https://api.sap.com/)
+
+**All 12 Files Extracted & Consolidated**: 2025-11-21
+
+**Compliance**: Follows official SAP API Style Guide and OpenAPI specifications
+
+---
+
+**End of REST and OData API Documentation Guide**
diff --git a/templates/odata-operation-template.md b/templates/odata-operation-template.md
new file mode 100644
index 0000000..7ead6ad
--- /dev/null
+++ b/templates/odata-operation-template.md
@@ -0,0 +1,681 @@
+# OData Operation Template
+
+## How to Use This Template
+
+**Purpose**: Document individual OData operations (CRUD, functions, actions) with complete request/response details.
+
+**When to Use**:
+- Creating detailed documentation for a specific OData operation
+- Documenting CRUD operations with full request/response examples
+- Documenting custom functions and actions
+- Detailed operation documentation linked from Resource template
+
+**Instructions**:
+1. Replace all [bracketed text] with your actual operation information
+2. Include complete, working HTTP request examples
+3. Show real response examples with actual data and status codes
+4. Document all possible status codes for this specific operation
+5. Include both success and error response examples
+6. Test the operation and verify all examples work
+7. Remove optional sections if not applicable
+
+**Cross-Reference**: Use with [OData Resource Template](#odata-resource-template) for resource context and [OData Service Overview Template](#odata-service-overview-template) for service-level info.
+
+**Template Structure**:
+- Title & Introduction
+- Operation Details (type, HTTP method, permission)
+- Request (headers, parameters, body, examples)
+- Response (headers, status codes, body, examples)
+
+---
+
+## [Operation Name] ([HTTP Method])
+
+[Provide comprehensive description of what this operation does. Include:
+- What action is performed
+- What is returned (if applicable)
+- When to use this operation
+- Important behaviors or side effects]
+
+**Example**:
+"Creates a new employee record in the system with provided information.
+Automatically assigns unique employee ID and initializes default values
+(status: ACTIVE, creation timestamp). Triggers HR workflow notifications."
+
+---
+
+## Usage
+
+[Explain when and why to use this operation, including:
+- Primary use cases and scenarios
+- When to use alternative operations
+- Important prerequisites or constraints
+- Any special behaviors or workflows]
+
+Use this operation to [describe scenario].
+
+Key points:
+- [Important characteristic or constraint]
+- [Related operation if applicable]
+- [Performance consideration if relevant]
+- [Workflow impact or side effect if relevant]
+
+**Example**:
+"Use this operation when adding a new employee to the system. Required fields
+include first name, last name, email, and department. Optional fields like
+hire date and salary can be provided.
+
+Key points:
+- Automatically generates unique EmployeeID
+- Email must be unique across system
+- Returns created employee in response body (if Prefer header included)
+- Triggers HR workflow notifications to department manager
+- Related operations: PATCH for updates, GET for retrieval"
+
+---
+
+## Request
+
+### Operation Details
+
+**URI**: [HTTP Method] [Path]
+
+**Example**: `POST /Employees`, `GET /Employees('E12345')`, `PATCH /Employees('E12345')`
+
+**Operation Type**: [CRUD/Function/Action]
+
+| Aspect | Value |
+|---|---|
+| HTTP Method | [GET/POST/PUT/PATCH/DELETE] |
+| Operation Type | [CRUD (standard)/Function (returns data)/Action (performs action)] |
+| Resource | [Resource name] |
+| Full URI Pattern | [Complete URI pattern with placeholders] |
+
+**Example**:
+```
+| Aspect | Value |
+|---|---|
+| HTTP Method | POST |
+| Operation Type | CRUD (Create) |
+| Resource | Employees |
+| Full URI Pattern | POST /Employees |
+```
+
+### Required Permission
+
+**Permission**: [Required role or permission level]
+
+[Explanation of what this permission allows and why it's required]
+
+**Example**:
+"Permission: ROLE_HR_MANAGER or ROLE_ADMIN
+
+Only users with ROLE_HR_MANAGER or higher role can create employees.
+Lower roles like ROLE_HR_USER cannot call this operation."
+
+### Request Headers
+
+| Header Name | Required | Possible Values | Description |
+|---|---|---|---|
+| [Header] | [Yes/No] | [Values] | [Description with format/examples] |
+
+**Example**:
+```
+| Header Name | Required | Possible Values | Description |
+|---|---|---|---|
+| Authorization | Yes | Bearer {token} | OAuth2 authentication token. Format: Bearer {token}. Required for all operations. |
+| Content-Type | Yes (POST/PUT/PATCH) | application/json | Media type of request body. Required for operations with request body. Value: application/json |
+| Accept | No | application/json | Preferred response format. Default: application/json. Optional: specify other formats if supported. |
+| Prefer | No | return=representation, return=minimal | OData preference. return=representation: include created/updated entity in response. return=minimal: response without body (faster). |
+| If-Match | No | {ETag} | ETag for optimistic concurrency control. Format: quoted string (e.g., "abc123"). Required for safe concurrent updates on PUT/PATCH. |
+| X-Request-ID | No | UUID | Optional request tracking ID. Format: any valid UUID. Example: 123e4567-e89b-12d3-a456-426614174000 |
+```
+
+### Request Parameters
+
+[Document all parameters passed to the operation, organized by location.]
+
+#### Path Parameters
+
+[If operation uses path parameters in URI]
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| [Name] | Required/Optional | [Type] | [Description with constraints, pattern, valid values] | Path |
+
+**Example**:
+```
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| EmployeeID | Required | String | Employee unique identifier. Pattern: E[0-9]{5}. Example: "E12345" | Path |
+```
+
+#### Query Parameters
+
+[If operation uses query parameters]
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| $filter | Optional | String | OData filter expression for query. Example: FirstName eq 'John'. Used only in GET collection operations. | Query |
+| $orderby | Optional | String | Sort order. Example: HireDate desc, LastName asc. Used in GET collection operations. | Query |
+| $top | Optional | Integer | Maximum records to return (1-1000). Default: 50. Used for pagination. | Query |
+| $skip | Optional | Integer | Records to skip for pagination. Default: 0. Used with $top. | Query |
+| $select | Optional | String | Properties to include in response. Example: FirstName,LastName,Email. Reduces payload size. | Query |
+| $expand | Optional | String | Navigate relationships and include related data. Example: Department,Manager. Limited to 3 levels deep. | Query |
+
+**Detailed Example for POST**:
+```
+[No query parameters for POST operations - all data in request body]
+```
+
+**Detailed Example for GET with Collection**:
+```
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| $filter | Optional | String | Filter expression. Example: $filter=Status eq 'ACTIVE' and Salary gt 100000 | Query |
+| $orderby | Optional | String | Sort fields. Example: $orderby=HireDate desc,LastName asc | Query |
+| $top | Optional | Integer | Max results (1-1000, default: 50). Example: $top=100 | Query |
+| $skip | Optional | Integer | Records to skip for pagination. Example: $skip=200 | Query |
+| $select | Optional | String | Properties to include. Example: $select=FirstName,LastName,Email | Query |
+| $expand | Optional | String | Include related data. Example: $expand=Department,Manager | Query |
+| $count | Optional | Boolean | Include total count. Returns entities with @odata.count. Value: true. Example: ?$count=true. Note: Path /Employees/$count returns only integer count. | Query |
+```
+
+#### Request Body
+
+[For POST/PUT/PATCH operations with request body]
+
+**Format**: [JSON structure with all properties]
+
+**Required Fields**: [List of required fields]
+
+**Optional Fields**: [List of optional fields]
+
+| Property Name | Requirement | Data Type | Description | Constraints |
+|---|---|---|---|---|
+| [Property] | Required/Optional | [Type] | [Description] | [Min/max, format, valid values] |
+
+**Example**:
+```
+Request body structure:
+
+{
+  "FirstName": "string",
+  "LastName": "string",
+  "Email": "string",
+  "Department": "string",
+  "HireDate": "date",
+  "Salary": "decimal"
+}
+
+Required Fields: FirstName, LastName, Email, Department
+
+Optional Fields: HireDate, Salary
+
+| Property Name | Requirement | Data Type | Description | Constraints |
+|---|---|---|---|---|
+| FirstName | Required | String | Employee's first name | 1-50 characters, alphanumeric + spaces |
+| LastName | Required | String | Employee's last name | 1-50 characters, alphanumeric + spaces |
+| Email | Required | String | Corporate email address | Must be unique, valid email format (RFC 5322) |
+| Department | Required | String | Department code | Valid: "SALES", "ENGINEERING", "FINANCE", "HR", "OPERATIONS" |
+| HireDate | Optional | Date | Hire date in YYYY-MM-DD format | Cannot be future date, ISO 8601 format |
+| Salary | Optional | Decimal | Annual salary in USD | Minimum: 20000, maximum: 10000000, 2 decimal places |
+```
+
+### Request Example
+
+[Provide complete, working HTTP request with all headers and body.]
+
+**Template**:
+```http
+[HTTP METHOD] [Path]?[Query Parameters] HTTP/1.1
+Host: [Host]
+Authorization: Bearer [token]
+Content-Type: application/json
+[Additional Headers]
+
+[Request body if applicable]
+```
+
+#### Example - GET Collection with Filtering
+
+```http
+GET /Employees?$filter=Status eq 'ACTIVE' and Department eq 'ENGINEERING'&$orderby=LastName asc&$top=50&$skip=0 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Accept: application/json
+```
+
+#### Example - GET Single Resource
+
+```http
+GET /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Accept: application/json
+```
+
+#### Example - POST (Create)
+
+```http
+POST /Employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+Prefer: return=representation
+
+{
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Salary": 95000.00
+}
+```
+
+#### Example - PATCH (Update)
+
+```http
+PATCH /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+If-Match: "abc123def456"
+
+{
+  "Department": "SALES",
+  "Salary": 105000.00
+}
+```
+
+#### Example - PUT (Replace)
+
+```http
+PUT /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+
+{
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "SALES",
+  "HireDate": "2024-01-15",
+  "Salary": 105000.00
+}
+```
+
+#### Example - DELETE
+
+```http
+DELETE /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+---
+
+## Response
+
+### Response Headers
+
+| Header Name | Description | Possible Values |
+|---|---|---|
+| [Header] | [What this header contains] | [Example values] |
+
+**Example**:
+```
+| Header Name | Description | Possible Values |
+|---|---|---|
+| Content-Type | Response body media type | application/json |
+| Location | URL of created/modified resource | [https://api.example.com/odata/v4/Employees('E12346](https://api.example.com/odata/v4/Employees('E12346)') |
+| ETag | Entity tag for caching and concurrency control | "abc123def456" |
+| OData-Version | OData protocol version used | 4.0 |
+| Preference-Applied | Which Prefer preference was applied | return=representation, return=minimal |
+```
+
+### Status Codes
+
+| Status Code | Description | Conditions | Response Body |
+|---|---|---|---|
+| [Code] | [What status means] | [When this occurs] | [Type of response body] |
+
+**Example for GET (200 OK)**:
+```
+| Status Code | Description | Conditions | Response Body |
+|---|---|---|---|
+| 200 OK | Request successful | Entity/collection retrieved | Entity or collection data |
+| 401 Unauthorized | Authentication required | Missing/invalid token | Error object |
+| 403 Forbidden | Insufficient permissions | User lacks required role | Error object |
+| 404 Not Found | Resource doesn't exist | Invalid ID/key | Error object |
+| 500 Internal Server Error | Server error | Unhandled exception | Error object |
+```
+
+**Example for POST (201 Created)**:
+```
+| Status Code | Description | Conditions | Response Body |
+|---|---|---|---|
+| 201 Created | Resource created successfully | Valid request, auto-generated ID | Created entity (if Prefer: return=representation) |
+| 400 Bad Request | Validation error | Invalid data, missing required field | Error object with details |
+| 401 Unauthorized | Authentication required | Missing/invalid token | Error object |
+| 403 Forbidden | Insufficient permissions | User lacks ROLE_HR_MANAGER | Error object |
+| 409 Conflict | Duplicate/constraint violation | Email already exists | Error object with details |
+| 500 Internal Server Error | Server error | Database error | Error object |
+```
+
+**Example for PATCH (204 No Content or 200 OK)**:
+```
+| Status Code | Description | Conditions | Response Body |
+|---|---|---|---|
+| 204 No Content | Update successful | Default response without Prefer header | Empty body |
+| 200 OK | Update successful | Prefer: return=representation | Updated entity data |
+| 400 Bad Request | Validation error | Invalid field values | Error object |
+| 401 Unauthorized | Authentication required | Missing/invalid token | Error object |
+| 403 Forbidden | Insufficient permissions | User lacks required role | Error object |
+| 404 Not Found | Resource doesn't exist | Invalid ID | Error object |
+| 412 Precondition Failed | Optimistic concurrency failure | If-Match ETag mismatch | Error object |
+| 500 Internal Server Error | Server error | Database error | Error object |
+```
+
+### Response Body (Successful)
+
+[Document the successful response body structure, including all properties.]
+
+```json
+{
+  "[property]": "[value or type]",
+  "[property]": "[value or type]"
+}
+```
+
+**Example for GET Single (200 OK)**:
+```json
+{
+  "EmployeeID": "E12345",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2020-06-01",
+  "Salary": 120000.00,
+  "Status": "ACTIVE",
+  "CreatedAt": "2020-06-01T09:00:00Z",
+  "LastModified": "2024-01-15T14:30:00Z"
+}
+```
+
+**Example for GET Collection (200 OK)**:
+```json
+{
+  "value": [
+    {
+      "EmployeeID": "E12345",
+      "FirstName": "John",
+      "LastName": "Doe",
+      "Email": "john.doe@company.com",
+      "Status": "ACTIVE"
+    },
+    {
+      "EmployeeID": "E12346",
+      "FirstName": "Jane",
+      "LastName": "Smith",
+      "Email": "jane.smith@company.com",
+      "Status": "ACTIVE"
+    }
+  ]
+}
+```
+
+**Example for POST (201 Created)**:
+```json
+{
+  "EmployeeID": "E12346",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Salary": 95000.00,
+  "Status": "ACTIVE",
+  "CreatedAt": "2024-01-15T10:30:00Z",
+  "LastModified": "2024-01-15T10:30:00Z"
+}
+```
+
+---
+
+## Complete Response Examples
+
+### Success Response (200 OK - GET)
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+ETag: "abc123def456"
+OData-Version: 4.0
+
+{
+  "EmployeeID": "E12345",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2020-06-01",
+  "Salary": 120000.00,
+  "Status": "ACTIVE",
+  "CreatedAt": "2020-06-01T09:00:00Z",
+  "LastModified": "2024-01-15T14:30:00Z"
+}
+```
+
+### Success Response (201 Created - POST)
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: [https://api.example.com/odata/v4/Employees('E12346](https://api.example.com/odata/v4/Employees('E12346)')
+ETag: "def789ghi123"
+OData-Version: 4.0
+
+{
+  "EmployeeID": "E12346",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2024-01-15",
+  "Salary": 95000.00,
+  "Status": "ACTIVE",
+  "CreatedAt": "2024-01-15T10:30:00Z",
+  "LastModified": "2024-01-15T10:30:00Z"
+}
+```
+
+### Success Response (204 No Content - PATCH)
+
+```http
+HTTP/1.1 204 No Content
+```
+
+### Success Response (Collection - GET with $top/$skip)
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+OData-Version: 4.0
+
+{
+  "value": [
+    {
+      "EmployeeID": "E12345",
+      "FirstName": "John",
+      "LastName": "Doe",
+      "Email": "john.doe@company.com",
+      "Department": "ENGINEERING",
+      "Status": "ACTIVE"
+    },
+    {
+      "EmployeeID": "E12346",
+      "FirstName": "Jane",
+      "LastName": "Smith",
+      "Email": "jane.smith@company.com",
+      "Department": "SALES",
+      "Status": "ACTIVE"
+    }
+  ]
+}
+```
+
+---
+
+## Error Response Examples
+
+### Error Response (400 Bad Request)
+
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed. See details for specific errors",
+    "details": [
+      {
+        "field": "Email",
+        "issue": "Email already exists in system",
+        "value": "john.doe@company.com",
+        "existingEmployeeId": "E10001"
+      },
+      {
+        "field": "Salary",
+        "issue": "Minimum salary must be at least 20000",
+        "value": "15000"
+      }
+    ]
+  }
+}
+```
+
+### Error Response (401 Unauthorized)
+
+```http
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "AUTHENTICATION_FAILED",
+    "message": "Authentication token missing, invalid, or expired",
+    "details": {
+      "reason": "Bearer token not provided in Authorization header"
+    }
+  }
+}
+```
+
+### Error Response (403 Forbidden)
+
+```http
+HTTP/1.1 403 Forbidden
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "INSUFFICIENT_PERMISSION",
+    "message": "Insufficient permissions for this operation",
+    "details": {
+      "requiredRole": "ROLE_HR_MANAGER",
+      "userRole": "ROLE_HR_USER",
+      "operation": "Create Employee"
+    }
+  }
+}
+```
+
+### Error Response (404 Not Found)
+
+```http
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Requested resource not found",
+    "details": {
+      "resourceType": "Employee",
+      "providedId": "E99999",
+      "suggestion": "Verify the employee ID exists and hasn't been deleted"
+    }
+  }
+}
+```
+
+### Error Response (409 Conflict - Duplicate)
+
+```http
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "DUPLICATE_EMAIL",
+    "message": "Employee with provided email already exists",
+    "details": {
+      "email": "john.doe@company.com",
+      "existingEmployeeId": "E10001",
+      "existingEmployeeName": "John Doe"
+    }
+  }
+}
+```
+
+### Error Response (500 Internal Server Error)
+
+```http
+HTTP/1.1 500 Internal Server Error
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "INTERNAL_SERVER_ERROR",
+    "message": "Server encountered an unexpected error",
+    "details": {
+      "traceId": "550e8400-e29b-41d4-a716-446655440000",
+      "timestamp": "2024-01-15T14:30:00Z",
+      "suggestion": "Contact support with provided trace ID"
+    }
+  }
+}
+```
+
+---
+
+## Special Cases / Additional Notes
+
+[Document any special behaviors, edge cases, or implementation notes]
+
+**Example**:
+- Soft delete: Employee records are marked with Status='TERMINATED', not physically deleted
+- Automatic fields: EmployeeID, CreatedAt, and LastModified are auto-generated
+- Optimistic concurrency: Use If-Match header with ETag to prevent lost updates
+- Batch operations: This operation can be included in a $batch request
+- Rate limiting: This operation counts as 1 request toward rate limit
+
+---
+
+## Related Operations
+
+- [Resource Overview](#odata-resource-[name])
+- [Service Overview](#odata-service-[name])
+- [Related Operation 1](#odata-operation-[name])
+- [Related Operation 2](#odata-operation-[name])
+
+---
+
+**Template Version**: 1.0
+**Last Updated**: 2025-11-21
+**Compliance**: SAP API Style Guide Section 50
diff --git a/templates/odata-resource-template.md b/templates/odata-resource-template.md
new file mode 100644
index 0000000..901e9cc
--- /dev/null
+++ b/templates/odata-resource-template.md
@@ -0,0 +1,557 @@
+# OData Resource Template
+
+## How to Use This Template
+
+**Purpose**: Document individual OData resources (entity sets) within a service with all available operations.
+
+**When to Use**:
+- Creating detailed documentation for a specific OData entity set/resource
+- Documenting all CRUD operations on a resource
+- Listing navigation properties and custom functions/actions
+- Linking from Service Overview to specific resource documentation
+
+**Instructions**:
+1. Replace all [bracketed text] with your actual resource information
+2. Verify all operations against service metadata
+3. Document navigation properties with cardinality (1:1, 1:N)
+4. Include permission requirements for each operation type
+5. List custom functions and actions with brief descriptions
+6. Remove optional sections if not applicable
+
+**Cross-Reference**: Use with [OData Service Overview Template](#odata-service-overview-template) for service context and [OData Operation Template](#odata-operation-template) for detailed operation docs.
+
+**Template Structure**:
+- Title & Introduction
+- Resource Information (path, key, permissions)
+- Operations (CRUD, navigation, custom)
+- Common Headers
+- Status and Error Codes
+- Examples
+
+---
+
+## [Resource Name] Resource
+
+[Provide clear description of what this resource represents and contains. Include:
+- What business entity or data domain it covers
+- Primary use cases
+- Relationship to other resources
+- Scope or limitations]
+
+**Example**:
+"Collection of all employees in the system. Provides access to employee master
+data including personal information, organizational assignments, employment
+status, and related compensation information. Navigation properties allow
+access to related departments, managers, and compensation details."
+
+### Additional Context
+
+[Any important information about this resource]
+
+This resource represents [explain domain/purpose]. Use for [primary use cases].
+Navigation properties allow [explain relationships].
+
+---
+
+## Resource Information
+
+### Resource Path
+
+**Path**: `[Relative path to entity set, e.g., /Employees]`
+
+[Explanation of resource path]
+
+### Absolute URI
+
+**Absolute URI**: `[Root URI]/[Resource Path]`
+
+**Example**: `[https://api.example.com/odata/v4/Employees`](https://api.example.com/odata/v4/Employees`)
+
+### Key Property
+
+**Key Property**: [Property name that uniquely identifies each resource]
+
+[Description of key property and format/pattern]
+
+**Example**:
+```
+Key Property: EmployeeID
+Type: String
+Format: E followed by 5 digits
+Pattern: E[0-9]{5}
+Example: E12345
+```
+
+### Individual Resource Addressing
+
+[How to address/access a single resource by key]
+
+**URI Pattern**: `[Resource Path]('{[Key Value]}')`
+
+**Examples**:
+- `/Employees('E12345')` - Address by string key
+- `/Employees(EmployeeID='E12345')` - Explicit property name
+- `[https://api.example.com/odata/v4/Employees('E12345](https://api.example.com/odata/v4/Employees('E12345)')` - Absolute URI
+
+### Required Permissions
+
+[Document permissions for different operation types on this resource]
+
+| Operation Type | Required Permission | Description |
+|---|---|---|
+| Read/Query | [Role] | [What permission is needed and what it allows] |
+| Create (POST) | [Role] | [Permission required] |
+| Update (PUT/PATCH) | [Role] | [Permission required] |
+| Delete | [Role] | [Permission required] |
+
+**Example**:
+```
+| Operation Type | Required Permission | Description |
+|---|---|---|
+| Read/Query | ROLE_HR_USER | Read-only access to all employee data |
+| Create (POST) | ROLE_HR_MANAGER | Create new employee records |
+| Update (PUT/PATCH) | ROLE_HR_MANAGER | Modify existing employee data |
+| Delete | ROLE_ADMIN | Delete employee records (limited to admins) |
+```
+
+### Resource Properties
+
+[Complete list of all properties available on this resource]
+
+| Property Name | Data Type | Description | Example | Notes |
+|---|---|---|---|---|
+| [Property] | [Type] | [Description] | [Example value] | [Nullable, constraints, etc.] |
+
+**Example**:
+```
+| Property Name | Data Type | Description | Example | Notes |
+|---|---|---|---|---|
+| EmployeeID | String | Unique employee identifier | E12345 | Key property, not null |
+| FirstName | String | Employee's first name | John | 1-50 characters, required |
+| LastName | String | Employee's last name | Doe | 1-50 characters, required |
+| Email | String | Corporate email address | john.doe@company.com | Must be unique, required |
+| HireDate | Date | Employment start date | 2024-01-15 | ISO 8601 format, optional |
+| Status | String | Employment status | ACTIVE | Values: ACTIVE, INACTIVE, ON_LEAVE, TERMINATED |
+| Salary | Decimal | Annual salary | 95000.00 | Nullable, 2 decimal places |
+| CreatedAt | DateTime | Record creation timestamp | 2024-01-15T10:30:00Z | UTC, auto-set |
+| LastModified | DateTime | Last modification timestamp | 2024-01-15T14:30:00Z | UTC, auto-updated |
+```
+
+---
+
+## Operations
+
+### CRUD Operations
+
+Standard Create, Read, Update, Delete operations available on this resource:
+
+| HTTP Method | Operation | URI | Description |
+|---|---|---|---|
+| GET | [Read Collection](#operation-read-collection) | `[Resource]` | Retrieve all resources |
+| GET | [Read Single](#operation-read-single) | `[Resource]('{Key}')` | Retrieve specific resource |
+| POST | [Create](#operation-create) | `[Resource]` | Create new resource |
+| PUT | [Replace](#operation-replace) | `[Resource]('{Key}')` | Replace entire resource |
+| PATCH | [Update](#operation-update) | `[Resource]('{Key}')` | Partial update resource |
+| DELETE | [Delete](#operation-delete) | `[Resource]('{Key}')` | Delete resource |
+
+**Example**:
+```
+| HTTP Method | Operation | URI | Description |
+|---|---|---|---|
+| GET | [Query all employees](#operation-read-collection) | `/Employees` | Retrieve all employees with optional filtering and paging |
+| GET | [Get single employee](#operation-read-single) | `/Employees('{EmployeeID}')` | Retrieve specific employee by ID |
+| POST | [Create employee](#operation-create) | `/Employees` | Create new employee record |
+| PUT | [Replace employee](#operation-replace) | `/Employees('{EmployeeID}')` | Replace entire employee record |
+| PATCH | [Update employee](#operation-update) | `/Employees('{EmployeeID}')` | Partial update of employee fields |
+| DELETE | [Delete employee](#operation-delete) | `/Employees('{EmployeeID}')` | Delete/deactivate employee |
+```
+
+### Navigation Properties
+
+[If resource has relationships to other entities, document navigation properties]
+
+**Navigation Properties**:
+
+| Navigation Name | Target Entity | Cardinality | Description |
+|---|---|---|---|
+| [Property] | [Entity] | [1:1 / 1:N] | [Description of relationship] |
+
+**Example**:
+```
+| Navigation Name | Target Entity | Cardinality | Description |
+|---|---|---|---|
+| Department | Department | 1:1 | Navigate to employee's department |
+| Manager | Employee | 1:1 | Navigate to employee's manager (another employee) |
+| DirectReports | Employee | 1:N | Navigate to employees reporting to this employee |
+| Compensation | Compensation | 1:1 | Navigate to compensation details |
+```
+
+**How to Use Navigation Properties**:
+
+Using `$expand` to include related data:
+```
+GET /Employees?$expand=Department HTTP/1.1
+
+Returns employee(s) with embedded Department entity data.
+```
+
+Using `$expand` with `$select` to limit properties:
+```
+GET /Employees?$expand=Department($select=DepartmentID,Name) HTTP/1.1
+
+Returns employee(s) with only specific Department properties included.
+```
+
+Multi-level expansion:
+```
+GET /Employees?$expand=Department,Manager($expand=Department) HTTP/1.1
+
+Includes Department for the employee and Department for the manager.
+Maximum expansion depth: [specify limit, e.g., 3 levels]
+```
+
+### Custom Functions and Actions
+
+[If resource supports custom functions or actions, document them]
+
+| Operation Type | Name | URI | Description |
+|---|---|---|---|
+| [Function/Action] | [Name] | [URI Pattern] | [Description] |
+
+**Example**:
+```
+| Operation Type | Name | URI | Description |
+|---|---|---|---|
+| Function | GetManager | `/Employees('{EmployeeID}')/GetManager()` | Get the direct manager of an employee |
+| Function | GetDirectReports | `/Employees('{EmployeeID}')/GetDirectReports()` | Get all direct reports of an employee |
+| Action | Promote | `/Employees('{EmployeeID}')/Promote` | Promote employee to next level (requires payload with details) |
+| Action | Deactivate | `/Employees('{EmployeeID}')/Deactivate` | Mark employee as inactive |
+```
+
+**Detailed Function/Action Information**:
+
+For each custom operation, provide:
+- Purpose and use case
+- Request parameters (if any)
+- Return type
+- Permission requirements
+- Example request/response
+
+---
+
+## Common Headers
+
+### Request Headers
+
+| Header Name | Required | Possible Values | Description |
+|---|---|---|---|
+| [Header] | [Yes/No] | [Values] | [Description with format/examples] |
+
+**Example**:
+```
+| Header Name | Required | Possible Values | Description |
+|---|---|---|---|
+| Authorization | Yes | Bearer {token} | OAuth2 authentication token in format: Authorization: Bearer {token} |
+| Content-Type | Yes (POST/PUT/PATCH) | application/json | Media type of request body for create/update operations |
+| Accept | No | application/json | Preferred response format. Default: application/json. Value: application/json |
+| Prefer | No | return=representation, return=minimal | OData preference. return=representation: include created/updated resource. return=minimal: response without body. |
+| If-Match | No | {ETag} | ETag value for optimistic concurrency control on PUT/PATCH. Example: "abc123def456". Prevents lost-update problem. |
+| X-Request-ID | No | UUID | Request tracking ID for logging and debugging. Any valid UUID format. Optional but recommended. |
+```
+
+### Response Headers
+
+| Header Name | Description | Example Value |
+|---|---|---|
+| [Header] | [What this header contains] | [Example] |
+
+**Example**:
+```
+| Header Name | Description | Example Value |
+|---|---|---|
+| Content-Type | Response body media type | application/json |
+| ETag | Entity tag for caching and optimistic concurrency | "abc123def456" |
+| Location | URL of newly created resource (201 responses) | [https://api.example.com/odata/v4/Employees('E12346](https://api.example.com/odata/v4/Employees('E12346)') |
+| OData-Version | OData protocol version | 4.0 |
+| Preference-Applied | Which Prefer header preference was applied | return=representation |
+```
+
+---
+
+## Status and Error Codes
+
+### Common Status Codes
+
+| Status Code | Description | Typical Scenarios |
+|---|---|---|
+| [Code] | [Description] | [When this occurs] |
+
+**Example**:
+```
+Success Codes:
+
+| Status Code | Description | Typical Scenarios |
+|---|---|---|
+| 200 OK | Request successful. Response body contains requested data. | GET operations, POST with Prefer: return=representation |
+| 201 Created | Resource successfully created. Location header contains new resource URL. | POST operations creating new entity |
+| 204 No Content | Request successful. No response body returned. | DELETE operations, PUT/PATCH with Prefer: return=minimal |
+
+Error Codes:
+
+| Status Code | Description | Typical Scenarios |
+|---|---|---|
+| 400 Bad Request | Invalid request format, syntax, or OData query error. Response includes error details. | Malformed filter syntax, missing required fields, invalid data types |
+| 401 Unauthorized | Authentication token missing, invalid, or expired. | Missing Authorization header, invalid token, expired token |
+| 403 Forbidden | Authenticated but insufficient permissions for operation. | User lacks required role, permission denied for operation |
+| 404 Not Found | Requested resource doesn't exist. | Invalid resource ID/key, deleted resource |
+| 409 Conflict | Request conflicts with current state (duplicate, constraint violation). | Duplicate key/email, unique constraint violation, data conflict |
+| 500 Internal Server Error | Server encountered unexpected error. | Unhandled server exception, database error |
+```
+
+---
+
+## Examples
+
+### Query All Resources
+
+Retrieve all resources with optional filtering, selection, ordering, and pagination:
+
+**Request**:
+```http
+GET /[ResourceName]?$filter=[filter]&$select=[properties]&$orderby=[property]&$top=[limit]&$skip=[offset] HTTP/1.1
+Host: [host]
+Authorization: Bearer {token}
+Accept: application/json
+```
+
+**Example - Get all active employees, sorted by name, limit 20**:
+```http
+GET /Employees?$filter=Status eq 'ACTIVE'&$select=EmployeeID,FirstName,LastName,Email&$orderby=LastName asc&$top=20&$skip=0 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Accept: application/json
+```
+
+**Response** (200 OK):
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+OData-Version: 4.0
+
+{
+  "value": [
+    {
+      "EmployeeID": "E12345",
+      "FirstName": "John",
+      "LastName": "Doe",
+      "Email": "john.doe@company.com"
+    },
+    {
+      "EmployeeID": "E12346",
+      "FirstName": "Jane",
+      "LastName": "Smith",
+      "Email": "jane.smith@company.com"
+    }
+  ]
+}
+```
+
+### Query Single Resource
+
+Retrieve a single resource by key:
+
+**Request**:
+```http
+GET /[ResourceName]('{Key}') HTTP/1.1
+Host: [host]
+Authorization: Bearer {token}
+Accept: application/json
+```
+
+**Example**:
+```http
+GET /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Accept: application/json
+```
+
+**Response** (200 OK):
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+ETag: "abc123def456"
+
+{
+  "EmployeeID": "E12345",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": "ENGINEERING",
+  "HireDate": "2020-06-01",
+  "Salary": 120000.00,
+  "Status": "ACTIVE"
+}
+```
+
+### Query with Navigation Expansion
+
+Include related entity data:
+
+**Request**:
+```http
+GET /Employees('E12345')?$expand=Department,Manager($select=FirstName,LastName) HTTP/1.1
+Host: api.example.com
+Authorization: Bearer {token}
+Accept: application/json
+```
+
+**Response** (200 OK):
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "EmployeeID": "E12345",
+  "FirstName": "John",
+  "LastName": "Doe",
+  "Email": "john.doe@company.com",
+  "Department": {
+    "DepartmentID": "ENG",
+    "Name": "Engineering",
+    "Location": "San Francisco"
+  },
+  "Manager": {
+    "FirstName": "Jane",
+    "LastName": "Smith"
+  },
+  "Status": "ACTIVE"
+}
+```
+
+### Create Resource
+
+Create a new resource:
+
+**Request**:
+```http
+POST /[ResourceName] HTTP/1.1
+Host: [host]
+Authorization: Bearer {token}
+Content-Type: application/json
+Prefer: return=representation
+
+[Request body with resource properties]
+```
+
+**Example**:
+```http
+POST /Employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+Prefer: return=representation
+
+{
+  "FirstName": "Michael",
+  "LastName": "Johnson",
+  "Email": "michael.johnson@company.com",
+  "Department": "SALES",
+  "HireDate": "2024-01-15",
+  "Salary": 85000.00
+}
+```
+
+**Response** (201 Created):
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: [https://api.example.com/odata/v4/Employees('E12347](https://api.example.com/odata/v4/Employees('E12347)')
+
+{
+  "EmployeeID": "E12347",
+  "FirstName": "Michael",
+  "LastName": "Johnson",
+  "Email": "michael.johnson@company.com",
+  "Department": "SALES",
+  "HireDate": "2024-01-15",
+  "Salary": 85000.00,
+  "Status": "ACTIVE",
+  "CreatedAt": "2024-01-15T10:30:00Z"
+}
+```
+
+### Update Resource
+
+Partially update a resource using PATCH:
+
+**Request**:
+```http
+PATCH /[ResourceName]('{Key}') HTTP/1.1
+Host: [host]
+Authorization: Bearer {token}
+Content-Type: application/json
+If-Match: "{ETag}"
+
+[Request body with properties to update]
+```
+
+**Example - Update salary and department**:
+```http
+PATCH /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+If-Match: "abc123def456"
+
+{
+  "Department": "ENGINEERING",
+  "Salary": 125000.00
+}
+```
+
+**Response** (204 No Content):
+```http
+HTTP/1.1 204 No Content
+```
+
+### Delete Resource
+
+Delete a resource:
+
+**Request**:
+```http
+DELETE /[ResourceName]('{Key}') HTTP/1.1
+Host: [host]
+Authorization: Bearer {token}
+```
+
+**Example**:
+```http
+DELETE /Employees('E12345') HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Response** (204 No Content):
+```http
+HTTP/1.1 204 No Content
+```
+
+---
+
+## Related Documentation
+
+- **Parent Service**: [Service Name](#[service-anchor])
+- **Detailed Operations**:
+  - [Create](#odata-operation-create)
+  - [Read](#odata-operation-read)
+  - [Update](#odata-operation-update)
+  - [Delete](#odata-operation-delete)
+- **Related Resources**: [Other Resource Name](#)
+
+---
+
+**Template Version**: 1.0
+**Last Updated**: 2025-11-21
+**Compliance**: SAP API Style Guide Section 50
diff --git a/templates/odata-service-overview-template.md b/templates/odata-service-overview-template.md
new file mode 100644
index 0000000..d4d34a6
--- /dev/null
+++ b/templates/odata-service-overview-template.md
@@ -0,0 +1,411 @@
+# OData Service Overview Template
+
+## How to Use This Template
+
+**Purpose**: Document a complete OData service with metadata, supported features, and resource listing.
+
+**When to Use**:
+- Creating documentation for an entire OData v2, v3, or v4 service
+- Need to document service-level metadata, features, and entity relationships
+- Providing comprehensive service overview before detailed resource documentation
+
+**Instructions**:
+1. Replace all [bracketed text] with your actual service information
+2. Verify OData version and supported features against actual service metadata
+3. Document complete entity data model with relationships
+4. Provide accurate metadata URI and service endpoints
+5. Test service metadata endpoint and verify all documented features
+6. Remove optional sections if not applicable
+
+**Cross-Reference**: Use with [OData Resource Template](#odata-resource-template) for individual resource documentation.
+
+**Template Structure**:
+- Title & Introduction
+- Overview (version, root URI, permissions)
+- OData Feature Support Matrix
+- Entity Data Model
+- Resources Table
+
+**Token Tip**: Service-level documentation prevents repetition across resource docs, saving ~50% of tokens.
+
+---
+
+## [Service Name] OData Service
+
+[Provide comprehensive description of the OData service. Include:
+- Main purpose of the service
+- What domains/business areas it covers
+- Types of entities available
+- Supported operations (CRUD, functions, actions)
+- Integration points or workflow support]
+
+**Example**:
+"Provides OData v4 API for accessing and managing employee data including
+personal information, organizational assignments, compensation details, and
+organizational hierarchy. Supports full CRUD operations with complex filtering,
+navigation between related entities, and advanced query capabilities."
+
+---
+
+## Overview
+
+### OData Version
+
+**Version**: [2.0 | 3.0 | 4.0]
+
+[Brief explanation of which OData version(s) this service supports. Note any compatibility modes or deprecated versions.]
+
+**Version Information**:
+- OData 2.0: Legacy version with limited features
+- OData 3.0: Widely supported, intermediate features
+- OData 4.0: Latest version with modern features (JSON support, complex types, etc.)
+
+**Example**:
+"OData Version: 4.0
+
+The service primarily supports OData v4.0 with modern JSON payload support,
+complex filtering, and navigation properties. Backward compatibility for v3.0
+available via `/odata/v3` endpoint prefix."
+
+### Root URI
+
+**Root URI**: `[Absolute service path, e.g., [https://api.example.com/odata/v4]`](https://api.example.com/odata/v4]`)
+
+[Explanation of how to construct full URIs from root and include example paths to available resources.]
+
+**Full Service Paths**:
+```
+Root: [https://api.example.com/odata/v4]
+
+Available resources:
+- Employees: [https://api.example.com/odata/v4/Employees]
+- Departments: [https://api.example.com/odata/v4/Departments]
+- Compensation: [https://api.example.com/odata/v4/Compensation]
+```
+
+### Required Permissions
+
+**Permissions**: [List roles and what they allow across the service]
+
+[Explain permission model and any global service-level permissions.]
+
+**Example**:
+```
+Required Permissions:
+- ROLE_HR_USER: Read-only access to all resources
+- ROLE_HR_MANAGER: Read and write access to employee and department data
+- ROLE_FINANCE: Read-only access to compensation data
+- ROLE_ADMIN: Full read/write/delete access to all resources
+```
+
+**Permission Model**:
+- Global service-level authentication required
+- Authentication via OAuth 2.0 Bearer token
+- Role-based access control (RBAC) determines allowed operations per resource
+- Some resources or operations may have additional permission requirements (see resource documentation)
+
+---
+
+## OData Feature Support
+
+Document which OData features and capabilities the service supports:
+
+| Feature | Supported | Notes |
+|---|---|---|
+| [OData Feature Name] | [Yes/No/Partial] | [Details, limits, or constraints] |
+
+**Detailed Example**:
+
+| Feature | Supported | Notes |
+|---|---|---|
+| Filtering ($filter) | Yes | All OData comparison operators supported (eq, ne, lt, le, gt, ge). Logical operators: and, or, not. String functions: contains, startswith, endswith, length, substring. Example: `$filter=FirstName eq 'John' and Status eq 'ACTIVE'` |
+| Ordering ($orderby) | Yes | Ascending (asc) and descending (desc) ordering. Single and multiple field sorting. Example: `$orderby=HireDate desc,LastName asc` |
+| Paging ($top, $skip) | Yes | Maximum 1000 records per request. Default page size: 50 records. Recommended: use $top with values 10-100. Example: `$top=50&$skip=100` |
+| Selection ($select) | Yes | Choose specific properties to include in response. Reduces payload and improves performance. Example: `$select=FirstName,LastName,Email` |
+| Expansion ($expand) | Yes | Navigate relationships with limit of 3 levels deep. Expands related entity data inline. Example: `$expand=Department,Manager($select=FirstName,LastName)` |
+| Counting ($count) | Yes | Get total count of matching records via `$count` endpoint. Example: `/Employees/$count` |
+| Functions | Yes | Custom business function operations available (see resource documentation for specifics). Functions return computed values. |
+| Actions | Partial | Limited action support for specific state-changing operations. See resource documentation for available actions. |
+| Batch Requests | Yes | Submit multiple operations in single request via `$batch` endpoint. Useful for bulk operations. |
+| Batch Change Sets | Yes | Group multiple write operations (POST/PUT/PATCH) in batch change set. Atomic execution. |
+| Media Resources | No | File upload/download not currently supported in this version. |
+| Null Propagation | Yes | Null values properly handled in filter expressions. |
+| Type Casts | Yes | Cast operations in filters (e.g., `cast(Salary, 'Edm.Decimal')`) |
+
+**Common OData Features Explained**:
+- **$filter**: Reduces result set to matching records
+- **$orderby**: Controls sort order of results
+- **$top/$skip**: Implements pagination
+- **$select**: Reduces payload by including only needed fields
+- **$expand**: Includes related entity data without separate calls
+- **$count**: Gets total available records for pagination UI
+
+---
+
+## Entity Data Model
+
+[Document the complete data model including entity types, properties, and relationships.]
+
+### Entity Types
+
+[List and describe each entity type in the service with key properties and relationships.]
+
+**Example**:
+
+**Employee Entity**:
+- **Purpose**: Represents individual employee record
+- **Key Property**: EmployeeID (string, format: E[0-9]{5})
+- **Key Properties**:
+  - EmployeeID (string): Unique identifier
+  - FirstName (string): First name
+  - LastName (string): Last name
+  - Email (string): Corporate email
+  - HireDate (date): Employment start date
+  - Status (string): Employment status (ACTIVE, INACTIVE, ON_LEAVE, TERMINATED)
+  - Salary (decimal): Annual compensation
+  - CreatedAt (datetime): Record creation timestamp
+  - LastModified (datetime): Last modification timestamp
+
+- **Navigation Properties**:
+  - Department: Single navigation to Department entity
+  - Manager: Single navigation to managing Employee entity
+  - Compensation: Single navigation to Compensation entity
+  - DirectReports (collection): All employees reporting to this employee
+
+**Department Entity**:
+- **Purpose**: Represents organizational departments
+- **Key Property**: DepartmentID (string)
+- **Key Properties**:
+  - DepartmentID (string): Unique identifier
+  - Name (string): Department name
+  - Manager (string): Managing employee ID
+  - Location (string): Physical location
+  - CostCenter (string): Cost center code
+
+- **Navigation Properties**:
+  - Employees (collection): All employees in department
+  - ParentDepartment: Parent department (for hierarchy)
+  - SubDepartments (collection): Child departments
+
+**Compensation Entity**:
+- **Purpose**: Salary and benefits information
+- **Key Property**: CompensationID (string)
+- **Key Properties**:
+  - CompensationID (string): Unique identifier
+  - EmployeeID (string): Foreign key to Employee
+  - BaseSalary (decimal): Base annual salary
+  - Currency (string): Salary currency code (USD, EUR, etc.)
+  - Benefits (string): Benefits description
+  - EffectiveDate (date): When compensation became effective
+
+- **Navigation Properties**:
+  - Employee: Single navigation back to Employee entity
+
+### Entity Relationships
+
+[Document how entities relate to each other.]
+
+**Example**:
+```
+Employee (1) ---> (1) Department
+Employee (1) ---> (1) Employee (Manager)
+Employee (1) <--- (N) Employee (DirectReports)
+Employee (1) ---> (1) Compensation
+Department (1) ---> (N) Employee
+Department (1) ---> (1) Department (ParentDepartment)
+Department (1) <--- (N) Department (SubDepartments)
+```
+
+**Relationship Details**:
+- One-to-One (1:1): One employee has one manager
+- One-to-Many (1:N): One department has many employees
+- Hierarchical: Departments can contain sub-departments up to 10 levels deep
+
+### Service Metadata URI
+
+**Metadata Endpoint**: `[Root URI]/$metadata`
+
+[Explain what metadata contains and how to use it.]
+
+**Example**:
+```
+Service Metadata URI: [https://api.example.com/odata/v4/$metadata](https://api.example.com/odata/v4/$metadata)
+
+This endpoint returns the complete service definition in CSDL (Common Schema Definition Language) format.
+Contains entity type definitions, property types, navigation properties, and available operations.
+Useful for:
+- Code generation in various programming languages
+- Understanding complete service structure
+- Discovering available properties and relationships
+- Building dynamic OData clients
+```
+
+**How to Access Metadata**:
+```http
+GET [https://api.example.com/odata/v4/$metadata](https://api.example.com/odata/v4/$metadata) HTTP/1.1
+Authorization: Bearer {token}
+Accept: application/xml
+```
+
+### Additional Model Notes
+
+[Document any important data model constraints, patterns, or behaviors.]
+
+**Example**:
+```
+- All timestamps use UTC format (ISO 8601 standard)
+- Employee IDs follow strict pattern: E[0-9]{5} (example: E12345)
+- Salary values stored in currency specified in Compensation entity
+- Department hierarchies can nest maximum 10 levels deep
+- All string properties are case-sensitive in filters
+- Datetime properties include millisecond precision
+- Decimal properties (salary) use 2 decimal places
+- Soft deletes: Terminated employees have Status='TERMINATED' but record remains
+```
+
+---
+
+## Resources
+
+[List all entity sets/collections available in the service with descriptions and paths.]
+
+The following resources are available in this OData service:
+
+| Resource Name | Description | Path |
+|---|---|---|
+| [Entity Set Name] | [Description of resource and primary use] | [Relative path] |
+
+**Detailed Example**:
+
+| Resource Name | Description | Path |
+|---|---|---|
+| [Employees](#odata-resource-employees) | Collection of all employees in system. Access employee master data including personal information, employment details, and compensation. | `/Employees` |
+| [Departments](#odata-resource-departments) | Organization departments and structure. Access department definitions and organizational hierarchy. | `/Departments` |
+| [Compensation](#odata-resource-compensation) | Employee compensation and benefits data. Access salary and benefits information linked to employees. | `/Compensation` |
+
+**Resource Guidelines**:
+- Resource names link to detailed resource documentation
+- Descriptions are concise but informative
+- Paths are relative to Root URI
+- Order resources alphabetically or by logical grouping
+
+---
+
+## Common Implementation Patterns
+
+[Document common patterns or recommended approaches for using the service.]
+
+### Query with Filtering and Paging
+
+Retrieve active employees with specific fields, sorted and paginated:
+```
+GET /Employees?$filter=Status eq 'ACTIVE'&$select=EmployeeID,FirstName,LastName,Email
+&$orderby=LastName asc&$top=50&$skip=0 HTTP/1.1
+```
+
+### Expanding Related Data
+
+Retrieve employees with their department and manager information:
+```
+GET /Employees?$expand=Department,Manager($select=FirstName,LastName)&$top=10 HTTP/1.1
+```
+
+### Complex Filtering
+
+Find employees in Sales department earning over 100,000:
+```
+GET /Employees?$filter=Department/Name eq 'SALES' and Salary gt 100000&$orderby=Salary desc HTTP/1.1
+```
+
+### Batch Requests
+
+Submit multiple operations in single request:
+```
+POST /$batch HTTP/1.1
+
+[Batch request format with change sets for multiple operations]
+```
+
+---
+
+## Authentication and Authorization
+
+[Document authentication mechanism required to access the service.]
+
+**Authentication Type**: OAuth 2.0 Bearer Token
+
+**Token Acquisition**:
+1. Obtain OAuth 2.0 token from authentication service
+2. Include token in Authorization header: `Authorization: Bearer {token}`
+3. Token expires after [time period] - obtain new token when expired
+
+**Required in Every Request**:
+```http
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+---
+
+## Rate Limiting and Quotas
+
+[Document any service-level rate limits or quotas.]
+
+**Rate Limit**: [requests per time period, e.g., 1000 requests per hour]
+
+**Tracked by**: User/API key
+
+**Rate Limit Headers**:
+- X-RateLimit-Limit: Maximum requests in window
+- X-RateLimit-Remaining: Requests remaining in current window
+- X-RateLimit-Reset: Unix timestamp when window resets
+
+**When Rate Limited**: 429 Too Many Requests response with Retry-After header.
+
+---
+
+## Error Handling
+
+[Document standard error response format for the service.]
+
+**Standard Error Response**:
+```json
+{
+  "error": {
+    "code": "[Error code]",
+    "message": "[Human-readable message]",
+    "details": {
+      "[field]": "[error detail]"
+    }
+  }
+}
+```
+
+**Common OData Error Codes**:
+- INVALID_REQUEST: Malformed request
+- INVALID_FILTER: Filter syntax error
+- RESOURCE_NOT_FOUND: Entity doesn't exist
+- PERMISSION_DENIED: Insufficient permissions
+- VALIDATION_ERROR: Data validation failure
+
+---
+
+## Additional Information
+
+**Maximum Request Payload**: [size limit, e.g., 10 MB]
+
+**Maximum Response Payload**: [size limit if applicable, e.g., 50 MB]
+
+**Supported Content Types**:
+- `application/json` (recommended, OData v4)
+- `application/xml` (OData CSDL metadata)
+
+**Related Documentation**:
+- [OData Specification](https://www.odata.org/documentation/)
+- [OData v4.0 Standard](https://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protocol-complete.html)
+- Service-Specific Documentation: [link]
+
+---
+
+**Template Version**: 1.0
+**Last Updated**: 2025-11-21
+**Compliance**: SAP API Style Guide Section 50
diff --git a/templates/rest-api-method-template.md b/templates/rest-api-method-template.md
new file mode 100644
index 0000000..c905c73
--- /dev/null
+++ b/templates/rest-api-method-template.md
@@ -0,0 +1,477 @@
+# REST API Method Template
+
+## How to Use This Template
+
+**Purpose**: Document individual REST API methods/endpoints with complete request and response details.
+
+**When to Use**:
+- Creating documentation for a specific REST method (GET, POST, PUT, PATCH, DELETE)
+- Detailed endpoint documentation linked from Overview template
+- Providing exact parameter requirements and response examples
+
+**Instructions**:
+1. Replace all [bracketed text] with your actual content
+2. Include complete, working HTTP request examples
+3. Show real response examples with actual status codes
+4. Document all possible status codes for this specific method
+5. Test the endpoint and verify all examples work
+6. Remove optional sections if not applicable
+
+**Cross-Reference**: Use with [REST API Overview Template](#rest-api-overview-template) for shared information.
+
+**Template Structure**:
+- Title & Introduction
+- Usage section
+- Request Details (method, permission, headers, parameters)
+- Request Example(s)
+- Response Details (status codes, body examples)
+- Response Examples (success and error cases)
+
+---
+
+## [Action Verb] [Resource Name]
+
+[Provide a clear, concise description of what this method does. Include:
+- Primary action performed
+- What is retrieved, created, modified, or deleted
+- Primary use case
+- Key limitations or behaviors]
+
+**Example**:
+"Retrieves a complete list of all employees in the system with support for
+filtering, sorting, and pagination. Returns employee summary data by default."
+
+### Usage
+
+[Explain when and why to use this method, including:
+- Specific scenarios where this method is appropriate
+- When to use alternative methods instead
+- Important prerequisites or constraints
+- Any special behaviors or side effects]
+
+Use this method when [explain primary scenario].
+
+Key points:
+- [Important characteristic, constraint, or behavior]
+- [Related method or alternative, if applicable]
+- [Performance consideration, size limit, or special note]
+- [Business logic or workflow impact, if relevant]
+
+**Example**:
+"Use this method to retrieve all employee records with optional filtering
+and pagination.
+
+Key points:
+- Supports filtering by multiple fields using query parameters
+- Returns paginated results (default: 20 per page, max: 100 per page)
+- Results sorted by employee ID unless otherwise specified via sortBy (e.g., sortBy=employeeId or sortBy=-employeeId for desc)
+- Related method: GET /employees/{employeeId} for retrieving specific employee data
+- Performance: Large result sets should use pagination to avoid timeout"
+
+---
+
+## Request
+
+### Request Line
+
+```
+[HTTP METHOD] [Relative URI Path]
+```
+
+**Example**:
+```
+GET /employees
+GET /employees/{employeeId}
+POST /employees
+PUT /employees/{employeeId}
+PATCH /employees/{employeeId}
+DELETE /employees/{employeeId}
+```
+
+### HTTP Method
+
+**Method**: [GET/POST/PUT/PATCH/DELETE]
+
+[Brief explanation of what this HTTP method does in this context]
+
+**Method Details**:
+- GET: Retrieves resource(s) without modifying server state
+- POST: Creates new resource with provided data
+- PUT: Replaces entire resource with new data
+- PATCH: Partially updates resource (merge semantics)
+- DELETE: Deletes or deactivates resource
+
+### Permission Requirement
+
+**Permission**: [Required role/permission for this method]
+
+[Explanation of what this permission allows or why it's required]
+
+**Example**:
+"Permission: ROLE_HR_MANAGER (read access)
+
+Users with ROLE_HR_MANAGER or higher can call this method.
+Lower roles like ROLE_HR_USER cannot access this endpoint."
+
+### Common Request Headers
+
+Refer to [Common Request Headers](#common-request-headers) in the API Overview.
+
+[List any method-specific headers not covered in Overview]
+
+**Additional headers for this method** (if applicable):
+- [Header name]: [Description specific to this method]
+
+**Example**:
+"Refer to Common Request Headers in overview.
+
+Additional method-specific headers:
+- X-Employee-View: Optional header to specify detail level ('summary', 'full', default: 'summary')"
+
+### Path Parameters
+
+[If method has path parameters, include table. Otherwise, state "None".]
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| [Name] | Required/Optional | [Type] | [Detailed description with constraints, pattern, valid values] | Path |
+
+**Example**:
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| employeeId | Required | String | Unique employee identifier. Format: E followed by 5 digits. Pattern: `E[0-9]{5}`. Example: "E12345" | Path |
+
+### Query Parameters
+
+[If method accepts query parameters, include table. Otherwise, state "None".]
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| [Name] | Required/Optional | [Type] | [Description with constraints, valid values, defaults] | Query |
+
+**Example**:
+
+| Parameter Name | Requirement | Data Type | Description | Location |
+|---|---|---|---|---|
+| limit | Optional | Integer | Maximum results per page. Range: 1-100. Default: 20. Example: "50" | Query |
+| offset | Optional | Integer | Number of results to skip for pagination. Default: 0. Used with limit for pagination. | Query |
+| department | Optional | String | Filter by department code. Valid: "SALES", "ENGINEERING", "FINANCE", "HR", "OPERATIONS". Example: "SALES" | Query |
+| status | Optional | String | Filter by employee status. Valid: "ACTIVE", "INACTIVE", "LEAVE", "TERMINATED". Default: all statuses. | Query |
+| sortBy | Optional | String | Sort field. Valid: "name", "hireDate", "department", "salary". Default: "name". Use - prefix for descending (e.g., "-hireDate") | Query |
+
+### Request Body
+
+[For POST/PUT/PATCH methods, document request body structure. For GET/DELETE, state "None".]
+
+**For POST/PUT/PATCH**:
+
+```json
+{
+  "[property]": "[value or type]",
+  "[property]": "[value or type]"
+}
+```
+
+**Example**:
+
+```json
+{
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2024-01-15",
+  "salary": 95000.00
+}
+```
+
+**Field Descriptions**:
+
+| Field Name | Requirement | Data Type | Description |
+|---|---|---|---|
+| [Name] | Required/Optional | [Type] | [Description with constraints, format, valid values, length, min/max] |
+
+**Example**:
+
+| Field Name | Requirement | Data Type | Description |
+|---|---|---|---|
+| firstName | Required | String | Employee's first name. Length: 1-50 characters. Alphanumeric and spaces only. |
+| lastName | Required | String | Employee's last name. Length: 1-50 characters. Alphanumeric and spaces only. |
+| email | Required | String | Corporate email address. Must be unique across system. Must be valid email format (RFC 5322). |
+| department | Required | String | Department code. Valid: "SALES", "ENGINEERING", "FINANCE", "HR", "OPERATIONS". Example: "ENGINEERING" |
+| hireDate | Optional | Date (YYYY-MM-DD) | Hire date of employee. Format: ISO 8601 date. Cannot be future date. Example: "2024-01-15" |
+| salary | Optional | Decimal | Annual salary in USD. Minimum: 20000. Maximum: 10000000. Two decimal places. Example: 95000.00 |
+
+---
+
+## Response
+
+### Status Codes
+
+[Document all HTTP status codes that can be returned by this specific method.]
+
+| Status Code | Description |
+|---|---|
+| [Code] | [What this status means in context of this specific operation] |
+
+**Example for GET method**:
+
+| Status Code | Description |
+|---|---|
+| 200 OK | Request successful. Response body contains employee data matching query. |
+| 400 Bad Request | Invalid query parameters or malformed request. Check parameter values and format. |
+| 401 Unauthorized | Authentication token missing, invalid, or expired. Obtain new token via authentication service. |
+| 403 Forbidden | Authenticated but insufficient permissions. User lacks ROLE_HR_USER required for read access. |
+| 404 Not Found | No employee found with specified ID (for single-resource GET). |
+| 429 Too Many Requests | Rate limit exceeded. Wait for X-RateLimit-Reset time before retrying. |
+| 500 Internal Server Error | Server encountered unexpected error. Contact support if issue persists. |
+
+**Example for POST method**:
+
+| Status Code | Description |
+|---|---|
+| 201 Created | Employee successfully created. Location header contains URL to new employee. Response includes created employee data. |
+| 400 Bad Request | Validation failed. Check email uniqueness, required fields, field formats, and value constraints. |
+| 401 Unauthorized | Authentication token missing, invalid, or expired. |
+| 403 Forbidden | Insufficient permissions. Requires ROLE_HR_MANAGER or higher. |
+| 409 Conflict | Employee with this email already exists. Email must be unique. |
+| 500 Internal Server Error | Server error. Contact support. |
+
+### Response Headers
+
+| Header Name | Description | Example Value |
+|---|---|---|
+| [Header name] | [What this header contains] | [Example value] |
+
+**Example**:
+
+| Header Name | Description | Example Value |
+|---|---|---|
+| Content-Type | Media type of response body | `application/json` |
+| X-Total-Count | Total available records (for paginated responses) | `5000` |
+| X-RateLimit-Remaining | API calls remaining in rate limit window | `998` |
+| Location | URL of created/modified resource (201, 200 responses) | `[https://api.example.com/v1/employees/E12346`](https://api.example.com/v1/employees/E12346`) |
+| ETag | Entity tag for caching and optimistic locking | `"abc123def456"` |
+
+### Response Body
+
+[Document the successful response body structure.]
+
+**For successful request**:
+
+```json
+{
+  "[property]": "[value]",
+  "[property]": "[value]"
+}
+```
+
+**Example**:
+
+```json
+{
+  "employeeId": "E12345",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "jobTitle": "Senior Software Engineer",
+  "hireDate": "2020-06-01",
+  "salary": 120000.00,
+  "status": "ACTIVE",
+  "createdAt": "2020-06-01T09:00:00Z",
+  "lastModified": "2024-01-15T14:30:00Z"
+}
+```
+
+---
+
+## Examples
+
+### Complete Request Example
+
+[Provide full HTTP request with all headers and body.]
+
+```http
+[HTTP METHOD] [Path]?[Query Parameters] HTTP/1.1
+Host: [Host from Base URI]
+Authorization: Bearer [token]
+Content-Type: application/json
+[Additional Headers]
+
+[Request Body (if applicable)]
+```
+
+**Example for GET**:
+
+```http
+GET /employees?limit=20&offset=0&status=ACTIVE HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Accept: application/json
+```
+
+**Example for POST**:
+
+```http
+POST /employees HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+
+{
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2024-01-15",
+  "salary": 95000.00
+}
+```
+
+**Example for PATCH**:
+
+```http
+PATCH /employees/E12345 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+If-Match: "abc123def456"
+
+{
+  "department": "SALES",
+  "salary": 105000.00
+}
+```
+
+### Complete Response Example (Success)
+
+```http
+HTTP/1.1 [Status Code] [Status Message]
+Content-Type: application/json
+[Response Headers]
+
+[Response Body]
+```
+
+**Example for 200 OK**:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+X-RateLimit-Remaining: 998
+ETag: "abc123def456"
+
+{
+  "employeeId": "E12345",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "jobTitle": "Senior Software Engineer",
+  "hireDate": "2020-06-01",
+  "salary": 120000.00,
+  "status": "ACTIVE",
+  "createdAt": "2020-06-01T09:00:00Z",
+  "lastModified": "2024-01-15T14:30:00Z"
+}
+```
+
+**Example for 201 Created**:
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+Location: [https://api.example.com/v1/employees/E12346](https://api.example.com/v1/employees/E12346)
+
+{
+  "employeeId": "E12346",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "department": "ENGINEERING",
+  "hireDate": "2024-01-15",
+  "status": "ACTIVE",
+  "salary": 95000.00,
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+### Error Response Examples
+
+**Example for 400 Bad Request**:
+
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "issue": "Email already exists",
+        "value": "john.doe@company.com"
+      },
+      {
+        "field": "salary",
+        "issue": "Minimum salary is 20000",
+        "value": "15000"
+      }
+    ]
+  }
+}
+```
+
+**Example for 404 Not Found**:
+
+```http
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Employee not found",
+    "details": {
+      "resourceType": "Employee",
+      "providedId": "E99999"
+    }
+  }
+}
+```
+
+**Example for 409 Conflict**:
+
+```http
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "DUPLICATE_EMPLOYEE",
+    "message": "Employee with email already exists",
+    "details": {
+      "email": "john.doe@company.com",
+      "existingEmployeeId": "E10001"
+    }
+  }
+}
+```
+
+---
+
+## Related Methods
+
+- [Parent Overview](#[rest-api-resource-name])
+- [Related Method 1](#[method-anchor])
+- [Related Method 2](#[method-anchor])
+
+---
+
+**Template Version**: 1.0
+**Last Updated**: 2025-11-21
+**Compliance**: SAP API Style Guide Section 50
diff --git a/templates/rest-api-overview-template.md b/templates/rest-api-overview-template.md
new file mode 100644
index 0000000..1ac6388
--- /dev/null
+++ b/templates/rest-api-overview-template.md
@@ -0,0 +1,217 @@
+# REST API Overview Template
+
+## How to Use This Template
+
+**Purpose**: Document a set of related REST API methods that apply to the same resource or service.
+
+**When to Use**:
+- Creating documentation for a REST API with multiple methods on the same resource
+- Need to document common properties shared by multiple endpoints
+- Want to provide an organized reference for all methods on a resource
+
+**Instructions**:
+1. Replace all [bracketed text] with your actual content
+2. Remove sections marked "Optional" if not applicable to your API
+3. Provide complete examples with real data
+4. Ensure all HTTP methods, URIs, and status codes are accurate
+5. Test all documented features before publishing
+
+**Template Structure**:
+- Title & Introduction (~100 words)
+- Base Information (URI, permissions, context)
+- Methods Table (all HTTP methods for the resource)
+- Common Request Headers
+- Common Response Headers
+- Status Codes
+
+**Token Tip**: This overview prevents repetition in detailed method docs, saving ~40% of documentation tokens while improving clarity.
+
+---
+
+## [Resource Name] REST API
+
+[Provide a brief 2-3 sentence description of what this REST API does. Include:
+- Main purpose of the API
+- What resources or operations it manages
+- Key capabilities (list, create, update, delete, etc.)
+- Any special features or scope]
+
+**Example**:
+"Provides methods to retrieve, create, update, and delete employee records.
+Supports querying employees by department, status, and other criteria.
+Fully supports pagination, filtering, and sorting."
+
+## Base Information
+
+**Base URI**: `[Absolute URI where API is hosted, e.g., [https://api.example.com/v1/employees]`](https://api.example.com/v1/employees]`)
+
+**Permissions**:
+- [Read/Query operations]: [Required role, e.g., ROLE_HR_USER]
+- [Write/Create operations]: [Required role, e.g., ROLE_HR_MANAGER]
+- [Delete operations]: [Required role, e.g., ROLE_ADMIN]
+
+**Example**:
+- Read: ROLE_HR_USER (can list and view employees)
+- Write: ROLE_HR_MANAGER (can create and modify employees)
+- Delete: ROLE_ADMIN (can permanently delete employees)
+
+**Additional Notes**:
+- [Any important API usage notes, e.g., "All requests require Bearer token authentication"]
+- [Pagination information, e.g., "API supports pagination with limit and offset parameters"]
+- [Rate limiting info, e.g., "Rate limit: 1000 requests per hour"]
+- [Special behaviors, e.g., "Soft deletes only - employee records are marked inactive, not removed"]
+
+## Methods
+
+The following table lists all HTTP methods available for this resource:
+
+| HTTP Method | Action | URI |
+|---|---|---|
+| [GET/POST/PUT/PATCH/DELETE] | [Link to detailed method documentation](#[anchor-link]) | [Relative URI path] |
+| [HTTP Method] | [Link](#[anchor]) | [Path] |
+
+**Example**:
+
+| HTTP Method | Action | URI |
+|---|---|---|
+| GET | [List All Employees](#list-all-employees) | `/employees` |
+| GET | [Get Employee by ID](#get-employee-by-id) | `/employees/{employeeId}` |
+| POST | [Create Employee](#create-employee) | `/employees` |
+| PUT | [Update Employee (Full Replace)](#update-employee) | `/employees/{employeeId}` |
+| PATCH | [Update Employee (Partial)](#update-employee-partial) | `/employees/{employeeId}` |
+| DELETE | [Delete Employee](#delete-employee) | `/employees/{employeeId}` |
+
+**Formatting Guidelines**:
+- Order methods by HTTP verb (GET, POST, PUT, PATCH, DELETE)
+- Make "Action" column links to detailed method documentation
+- Use consistent URI naming (e.g., `{employeeId}` for path parameters)
+- URI is relative to Base URI
+
+## Common Request Headers
+
+The following headers are used in requests to this API:
+
+| Header Name | Required | Description |
+|---|---|---|
+| [Header name] | [Yes/No] | [Description with possible values and format] |
+
+**Example**:
+
+| Header Name | Required | Description |
+|---|---|---|
+| Authorization | Yes | Bearer token for authentication. Format: `Authorization: Bearer {token}`. Obtain token from authentication service. |
+| Content-Type | Yes | Media type of request body. Value: `application/json`. Required for POST, PUT, PATCH requests. |
+| Accept | No | Preferred response format. Value: `application/json`. Default if not specified: `application/json`. |
+| X-Request-ID | No | Optional request ID for tracking and debugging. Format: UUID (e.g., `123e4567-e89b-12d3-a456-426614174000`). Any valid UUID accepted. |
+| If-Match | No | ETag for optimistic locking on PUT/PATCH requests. Format: quoted string (e.g., `"abc123def456"`). Required when implementing concurrent update protection. |
+
+**Field Descriptions**:
+- **Header Name**: Exact header name (case-sensitive)
+- **Required**: Yes if must be present; No if optional
+- **Description**: Purpose, accepted values, format, constraints, and default values
+
+## Common Response Headers
+
+The following headers appear in responses from this API:
+
+| Header Name | Description |
+|---|---|
+| [Header name] | [Purpose and possible values] |
+
+**Example**:
+
+| Header Name | Description |
+|---|---|
+| Content-Type | Type of response body. Always `application/json`. |
+| X-Total-Count | Total number of available resources (included in paginated responses). Example: `5000` |
+| X-RateLimit-Limit | Maximum API calls allowed in rate limit window. Example: `1000` |
+| X-RateLimit-Remaining | Number of API calls remaining in current window. Example: `998` |
+| X-RateLimit-Reset | Timestamp when rate limit resets (Unix seconds). Example: `1642123456` |
+| Location | URL of newly created resource (included in 201 Created responses). Format: Absolute URL. Example: `[https://api.example.com/v1/employees/E12346`](https://api.example.com/v1/employees/E12346`) |
+| ETag | Entity tag for caching and optimistic locking. Format: Quoted string. Example: `"abc123def456"` |
+
+## Status Codes
+
+All HTTP status codes that can be returned by methods in this API are documented below:
+
+**Success Codes**:
+
+| Status Code | Result Description |
+|---|---|
+| 200 OK | Request successful. Response body contains requested data. |
+| 201 Created | Resource successfully created. Location header contains URL to new resource. Response body typically contains created object. |
+| 204 No Content | Request successful. No response body returned. Typically for DELETE operations or updates with `Prefer: return=minimal`. |
+
+**Error Codes**:
+
+| Status Code | Result Description |
+|---|---|
+| 400 Bad Request | Invalid request format, syntax, or validation failure. Response body contains error details. Check request format, required fields, and parameter values. |
+| 401 Unauthorized | Authentication required or authentication token invalid/expired. Obtain new token or verify Bearer token format. |
+| 403 Forbidden | Authenticated but insufficient permissions for operation. Request ROLE_[appropriate role] permission assignment. |
+| 404 Not Found | Requested resource doesn't exist. Verify resource ID/URI and that resource hasn't been deleted. |
+| 409 Conflict | Request conflicts with current resource state (e.g., duplicate email, unique constraint violation). Resource may already exist or data constraint prevents operation. |
+| 410 Gone | Resource previously existed but is now deleted. Resource cannot be recovered. |
+| 429 Too Many Requests | Rate limit exceeded. See X-RateLimit-Reset header for when to retry. Implement exponential backoff. |
+| 500 Internal Server Error | Server encountered unexpected error. Contact support if issue persists. |
+| 503 Service Unavailable | Service temporarily unavailable (maintenance, overload). Retry after delay. See Retry-After header if present. |
+
+**Common Error Response Body Structure**:
+
+```json
+{
+  "error": {
+    "code": "[Error code identifier]",
+    "message": "[Human-readable error message]",
+    "details": {
+      "[field or property]": "[specific error detail]"
+    }
+  }
+}
+```
+
+---
+
+## Additional Information
+
+### Rate Limiting
+
+[Document rate limiting policy if applicable]
+- Limit: [requests per time period, e.g., 1000 requests per hour]
+- Tracking: [Rate limit headers used for tracking]
+- Handling: [What happens when limit exceeded and how to recover]
+
+### Pagination
+
+[Document pagination approach if applicable]
+- Query Parameters: [e.g., limit and offset]
+- Default Size: [default number of results]
+- Maximum Size: [maximum allowed per request]
+- Response Structure: [how pagination info appears in response]
+
+### Filtering and Sorting
+
+[Document if API supports query-based filtering/sorting]
+- Filtering Syntax: [explain parameter format]
+- Sortable Fields: [list fields that support sorting]
+- Example: [provide sample filter/sort query]
+
+### Error Handling Best Practices
+
+- Always check status code before processing response body
+- Implement exponential backoff for retryable errors (5xx, 429)
+- Parse error response for details about what went wrong
+- Log error codes and messages for debugging
+- Distinguish between client errors (4xx) and server errors (5xx)
+
+---
+
+## Related Documentation
+
+- [API Style Guide - Manual REST and OData Documentation](https://github.com/SAP-docs/api-style-guide)
+- [OAuth 2.0 Authentication](https://oauth.net/2/)
+- [HTTP Status Codes Reference (RFC 9110)](https://www.rfc-editor.org/rfc/rfc9110.html#status.codes)
+
+**Template Version**: 1.0
+**Last Updated**: 2025-11-21
+**Compliance**: SAP API Style Guide Section 50