gh-secondsky-sap-skills-skills-sap-api-style/templates/odata-service-overview-template.md

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

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	Collection of all employees in system. Access employee master data including personal information, employment details, and compensation.	/Employees
Departments	Organization departments and structure. Access department definitions and organizational hierarchy.	/Departments
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:

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:

{
  "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
• OData v4.0 Standard
• Service-Specific Documentation: [link]

---

Template Version: 1.0 Last Updated: 2025-11-21 Compliance: SAP API Style Guide Section 50