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

411
templates/odata-service-overview-template.md Normal file
View File

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