/sap-api-style

name: sap-api-style
description: |
  This skill provides comprehensive guidance for documenting SAP APIs following the 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:
  maintainer: "Eduard Jiglau"
  maintainer_email: "hello@sap-ai-skills.com"
  website: "https://sap-ai-skills.com"
  version: "2.4.1"
  last_verified: "2026-02-25"
  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) 12. [Common Issues](#common-issues)

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)

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-referenc