zhongwei/gh-secondsky-sap-skills-skills-sap-api-style
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:54:44 +08:00
commit f14894054f
17 changed files with 15633 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

664
references/deprecation-policy.md Normal file
View File

@@ -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)

704
references/developer-guides.md Normal file
View File

@@ -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)

472
references/glossary-resources.md Normal file
View File

@@ -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`, `<summary>`, `\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 `<exception>` 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 `<returns>` 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)

1517
references/java-javascript-dotnet-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

2765
references/manual-templates-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

2059
references/naming-conventions.md Normal file
View File

File diff suppressed because it is too large Load Diff

1774
references/quality-processes.md Normal file
View File

File diff suppressed because it is too large Load Diff

2800
references/rest-odata-openapi-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff