Initial commit
This commit is contained in:
Zhongwei Li
681
templates/odata-operation-template.md
Normal file
681
templates/odata-operation-template.md
Normal file
@@ -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
|
||||
|
||||
```
|
||||
|
||||
#### Example - PATCH (Update)
|
||||
|
||||
```http
|
||||
PATCH /Employees('E12345') HTTP/1.1
|
||||
Host: api.example.com
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
Content-Type: application/json
|
||||
If-Match: "abc123def456"
|
||||
|
||||
```
|
||||
|
||||
#### Example - PUT (Replace)
|
||||
|
||||
```http
|
||||
PUT /Employees('E12345') HTTP/1.1
|
||||
Host: api.example.com
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Response Examples
|
||||
|
||||
### Error Response (400 Bad Request)
|
||||
|
||||
```http
|
||||
HTTP/1.1 400 Bad Request
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Error Response (401 Unauthorized)
|
||||
|
||||
```http
|
||||
HTTP/1.1 401 Unauthorized
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Error Response (403 Forbidden)
|
||||
|
||||
```http
|
||||
HTTP/1.1 403 Forbidden
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Error Response (404 Not Found)
|
||||
|
||||
```http
|
||||
HTTP/1.1 404 Not Found
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Error Response (409 Conflict - Duplicate)
|
||||
|
||||
```http
|
||||
HTTP/1.1 409 Conflict
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Error Response (500 Internal Server Error)
|
||||
|
||||
```http
|
||||
HTTP/1.1 500 Internal Server Error
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
{
|
||||
"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
|
||||
557
templates/odata-resource-template.md
Normal file
557
templates/odata-resource-template.md
Normal file
@@ -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
|
||||
411
templates/odata-service-overview-template.md
Normal file
411
templates/odata-service-overview-template.md
Normal 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
|
||||
477
templates/rest-api-method-template.md
Normal file
477
templates/rest-api-method-template.md
Normal file
@@ -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
|
||||
217
templates/rest-api-overview-template.md
Normal file
217
templates/rest-api-overview-template.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user