x-readiness-mcp 0.3.0

package/templates/master_template.md

@@ -0,0 +1,374 @@
+# Siemens X-API Readiness Master Checklist
+
+**Version:** 2.5.0  
+**Last Updated:** 2026-01-28  
+**Description:** Master template for X-API readiness validation based on Siemens API Guidelines
+
+---
+
+## Sources
+
+### Common API Guidelines
+- Common API Guidelines - Overview
+- API Lifecycle Phases
+- API Specification
+- API Documentation
+- API Versioning
+- JSON Property Naming
+- HTTP API Protection
+- Common Guidelines Changelog
+
+### REST API Guidelines
+- REST API Guidelines - Overview
+- Media Types
+- REST Versioning
+- Error Handling
+- Common Operations
+- Bulk Operations
+- Sparse Fieldsets
+- Filtering
+- Pagination
+- Sorting
+- Security
+- Best Practices
+- Tools
+- Appendix: Data Types
+- REST Guidelines Changelog
+
+---
+
+## Scopes
+
+### x_api_readiness
+**Description:** Full X-API readiness check covering all common and REST guidelines
+
+**Includes:**
+- All Common Guidelines
+- All REST Guidelines
+
+---
+
+### pagination_ready
+**Description:** Pagination readiness including related query operations
+
+**Includes:**
+- Pagination
+- Sorting
+- Filtering
+- Sparse Fieldsets
+- Common Operations
+- Error Handling
+- Security
+- JSON Property Naming
+
+---
+
+### security_ready
+**Description:** Security readiness for API protection
+
+**Includes:**
+- Security
+- HTTP API Protection
+- Error Handling
+
+---
+
+### error_handling_ready
+**Description:** Error handling and status code compliance
+
+**Includes:**
+- Error Handling
+- Media Types
+- JSON Property Naming
+
+---
+
+### versioning_ready
+**Description:** API versioning compliance
+
+**Includes:**
+- API Versioning
+- REST Versioning
+- Media Types
+
+---
+
+### media_types_ready
+**Description:** Media types and naming conventions
+
+**Includes:**
+- Media Types
+- JSON Property Naming
+
+---
+
+### operations_ready
+**Description:** CRUD and bulk operations compliance
+
+**Includes:**
+- Common Operations
+- Bulk Operations
+- Error Handling
+
+---
+
+### query_ready
+**Description:** Query capabilities: filtering, sorting, sparse fieldsets
+
+**Includes:**
+- Filtering
+- Sorting
+- Sparse Fieldsets
+- Pagination
+
+---
+
+## Rule Categories
+
+### 1. PAGINATION
+**Priority:** High  
+**Guideline:** [Pagination](https://developer.siemens.com/guidelines/api-guidelines/rest/pagination.html)
+
+**Rules:**
+- 600: Pagination links
+- 601: Pagination strategies
+- 601.1: Cursor based strategy
+- 601.1.1: Server MAY provide pagination meta information
+- 601.2: Offset based strategy
+- 601.2.1: Offset pagination meta information
+- 601.3: Index based strategy
+- 601.3.1: Index pagination meta information
+
+---
+
+### 2. ERROR_HANDLING
+**Priority:** Critical  
+**Guideline:** [Error Handling](https://developer.siemens.com/guidelines/api-guidelines/rest/error.html)
+
+**Rules:**
+- 300: API MUST use official HTTP status codes as intended
+- 301: API SHOULD only use most common HTTP status codes
+- 301.3: Client Error 4xx Status Codes
+- 301.4: Server Error 5xx Status Codes
+- 302: API SHOULD use most specific HTTP status code for error
+- 303: API SHOULD not expose stack traces of the error
+- 304: API SHOULD report problems with an errors object
+- 305: Error object SHOULD be represented according to defined structure
+- 305.1: The values of the code field SHOULD be unique
+- 305.2: All error codes SHOULD be documented
+- 305.3: The values of title and detail fields SHOULD be in English
+
+---
+
+### 3. MEDIA_TYPES
+**Priority:** High  
+**Guideline:** [Media Types](https://developer.siemens.com/guidelines/api-guidelines/rest/media-type.html)
+
+**Rules:**
+- 100: API SHOULD use JSON-based media types
+- 101: API SHOULD use the following document structure
+- 101.1: API SHOULD use a top-level JSON object
+- 101.2: API SHOULD use the defined document structure
+- 101.3: The primary data MUST be represented by resource objects
+- 101.4: API MUST represent resources with resource objects
+- 101.4.1: Fields MUST follow the naming convention
+- 101.5: A links object SHOULD contain one or more links
+- 101.6: A link SHOULD be represented according to defined structure
+- 101.6.1: A link object SHOULD have defined structure fields
+- 101.7: A JSON document MAY provide meta information
+- 101.7.1: A meta field MUST contain meta information
+- 101.7.2: meta MUST be represented as JSON object
+- 101.7.3: meta fields SHOULD consider common field semantics
+- 101.8: Field names SHOULD apply naming conventions
+- 101.8.1: Field names MUST use allowed characters only
+- 101.9: Resource names SHOULD be in lowercase with hyphens
+- 102: Collection resource names SHOULD pluralize single resource
+
+---
+
+### 4. NAMING_CONVENTIONS
+**Priority:** Medium  
+**Guideline:** [JSON Property Naming](https://developer.siemens.com/guidelines/api-guidelines/common/json-property-naming.html)
+
+**Rules:**
+- naming_01: Names MUST start with a lower case letter
+- naming_02: Names MUST use camelCase for multi-word concatenation
+- naming_03: Abbreviations and acronyms MUST be treated as words
+- naming_04: Names MUST only consist of ASCII characters
+- naming_05: Words in names SHOULD use American English
+- naming_06: Names SHOULD be kept short and concise
+- naming_07: Resource names SHOULD use kebab-case
+- naming_08: Abbreviations SHOULD NOT be used except commonly used forms
+
+---
+
+### 5. SECURITY
+**Priority:** Critical  
+**Guideline:** [Security](https://developer.siemens.com/guidelines/api-guidelines/rest/security.html) | [HTTP API Protection](https://developer.siemens.com/guidelines/api-guidelines/common/http-api-protection.html)
+
+**Rules:**
+- sec_01: REST APIs MUST be secured with OAuth 2.0 Bearer Token
+- sec_02: APIs MUST use TLS for HTTP protection
+- sec_03: Token format SHOULD be JWT
+- sec_04: API implementation MUST check token signature
+- sec_05: API implementation MUST check token expiry
+- sec_06: API implementation MUST check token issuer
+- sec_07: API implementation MUST check scope
+- sec_08: API implementation SHOULD check token audience
+- sec_09: Authorization header with Bearer token SHOULD be present
+
+---
+
+### 6. VERSIONING
+**Priority:** Medium  
+**Guideline:** [API Versioning](https://developer.siemens.com/guidelines/api-guidelines/common/api-versioning.html) | [REST Versioning](https://developer.siemens.com/guidelines/api-guidelines/rest/versioning.html)
+
+**Rules:**
+- 200: API version in HTTP requests
+- 200.1: Option 1 - API version in URI path
+- 200.2: Option 2 - API version in custom request header
+- 201: API Version in HTTP Responses
+- ver_01: Version number MUST be expressed as MAJOR.MINOR.PATCH
+- ver_02: MUST increment MAJOR for incompatible changes
+- ver_03: MUST increment MINOR for backward compatible additions
+- ver_04: MUST increment PATCH for backward compatible fixes
+
+---
+
+### 7. COMMON_OPERATIONS
+**Priority:** High  
+**Guideline:** [Common Operations](https://developer.siemens.com/guidelines/api-guidelines/rest/common-operations.html)
+
+**Rules:**
+- ops_01: Use appropriate HTTP methods for operations
+- ops_02: GET requests MUST be safe and idempotent
+- ops_03: PUT and DELETE MUST be idempotent
+- ops_04: POST creates new resources
+- ops_05: Use PATCH for partial updates
+
+---
+
+### 8. BULK_OPERATIONS
+**Priority:** Medium  
+**Guideline:** [Bulk Operations](https://developer.siemens.com/guidelines/api-guidelines/rest/bulk-operations.html)
+
+**Rules:**
+- bulk_01: Support bulk operations for efficiency
+- bulk_02: Provide partial success reporting
+
+---
+
+### 9. FILTERING
+**Priority:** Medium  
+**Guideline:** [Filtering](https://developer.siemens.com/guidelines/api-guidelines/rest/filtering.html)
+
+**Rules:**
+- 400: API MAY support filtering
+- filter_01: Use query parameters for filtering
+- filter_02: Support common filter operations
+
+---
+
+### 10. SORTING
+**Priority:** Low  
+**Guideline:** [Sorting](https://developer.siemens.com/guidelines/api-guidelines/rest/sorting.html)
+
+**Rules:**
+- 700: API MAY provide sorting of collections
+- 700.1: Parameter sort MUST specify sort fields
+- 700.2: API MAY support multiple sort fields
+- 700.3: API MAY support defining sort order per field
+
+---
+
+### 11. SPARSE_FIELDSETS
+**Priority:** Low  
+**Guideline:** [Sparse Fieldsets](https://developer.siemens.com/guidelines/api-guidelines/rest/sparse-fieldsets.html)
+
+**Rules:**
+- 500: API MAY support sparse fieldsets
+- fields_01: Use fields parameter for field selection
+
+---
+
+## Compliance Levels
+
+### Basic Compliance (30%)
+**Description:** MUST requirements only for critical categories
+
+**Categories:**
+- SECURITY
+- ERROR_HANDLING
+
+**Required Rules:** 9
+
+---
+
+### Recommended Compliance (80%)
+**Description:** All MUST and SHOULD requirements
+
+**Categories:**
+- SECURITY
+- ERROR_HANDLING
+- MEDIA_TYPES
+- PAGINATION
+- NAMING_CONVENTIONS
+- VERSIONING
+
+**Required Rules:** 60
+
+---
+
+### Full X-Readiness (100%)
+**Description:** All standards including MAY considerations
+
+**Categories:**
+- PAGINATION
+- ERROR_HANDLING
+- MEDIA_TYPES
+- NAMING_CONVENTIONS
+- SECURITY
+- VERSIONING
+- COMMON_OPERATIONS
+- BULK_OPERATIONS
+- FILTERING
+- SORTING
+- SPARSE_FIELDSETS
+
+**Estimated Rules:** 80
+
+---
+
+## Quick Summary
+
+| Category | Priority | Rules Count |
+|----------|----------|-------------|
+| PAGINATION | High | 8 |
+| ERROR_HANDLING | Critical | 11 |
+| MEDIA_TYPES | High | 18 |
+| NAMING_CONVENTIONS | Medium | 8 |
+| SECURITY | Critical | 9 |
+| VERSIONING | Medium | 8 |
+| COMMON_OPERATIONS | High | 5 |
+| BULK_OPERATIONS | Medium | 2 |
+| FILTERING | Medium | 3 |
+| SORTING | Low | 4 |
+| SPARSE_FIELDSETS | Low | 2 |
+| **TOTAL** | | **~80** |
+
+---
+
+**Intent Keywords Mapping:**
+
+- **pagination, paging, page** → PAGINATION
+- **error, error handling** → ERROR_HANDLING
+- **media type, content type, json** → MEDIA_TYPES
+- **naming, camelCase** → NAMING_CONVENTIONS
+- **security, auth, oauth, jwt** → SECURITY
+- **versioning, version** → VERSIONING
+- **sorting, sort** → SORTING
+- **filtering, filter** → FILTERING
+- **bulk, batch** → BULK_OPERATIONS
+- **sparse, fields** → SPARSE_FIELDSETS
+- **operations, crud** → COMMON_OPERATIONS
+- **x-readiness, api readiness, full check** → All Categories