Instruction file imported from krizzo101/arxiv-py-enhanced (.cursor/rules/1230-api-versioning.mdc). Copyright stays with the author.

api-versioning

1.0.1

Metadata

{ "rule_id": "1230-api-versioning", "taxonomy": { "category": "Web and API Development Rules", "parent": "Web and API Development RulesRule", "ancestors": [ "Rule", "Web and API Development RulesRule" ], "children": [ "1231-api-versioning-best-practices", "1232-api-versioning-strategies" ] }, "tags": [ "API", "Versioning", "Web Development", "Best Practices" ], "priority": "70", "inherits": [ "000", "020", "030" ] }

Overview

{ "purpose": "MUST implement API versioning TO maintain backward compatibility and ensure that clients can continue to function as new features and updates are introduced.", "application": "SHOULD be applied during the design and implementation phases of API development, particularly WHEN making changes that could affect existing clients. Versioning MUST be incorporated into the API's endpoint structure or header information.", "importance": "This rule matters because it prevents breaking changes in APIs that could lead to client applications failing, ensuring a stable and reliable integration experience for users and developers." }

versioning_strategies

{ "description": "This section outlines the strategies for implementing API versioning effectively.", "requirements": [ "MUST define a versioning scheme (e.g., URI versioning, query parameter versioning, or header versioning) that aligns with your API's use case.", "SHOULD increment the version number WHEN introducing breaking changes to the API.", "MUST ensure that the version information is clearly documented and accessible to clients." ] }

backward_compatibility

{ "description": "This section details the requirements for maintaining backward compatibility during API updates.", "requirements": [ "MUST avoid removing or altering existing endpoints WITHOUT providing an alternative version.", "SHOULD support multiple active versions of the API simultaneously TO allow clients to migrate at their own pace.", "MUST communicate deprecation of older versions WELL in advance, providing clients with sufficient time to adapt." ] }

testing_and_validation

{ "description": "This section covers the importance of testing various API versions to ensure they function as intended.", "requirements": [ "MUST implement automated tests for each version of the API TO ensure compatibility and functionality.", "SHOULD include version-specific tests in the CI/CD pipeline TO catch issues early.", "MUST validate that changes in a new version do not adversely affect existing clients' functionality." ] }

const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

// Middleware to parse JSON request bodies
app.use(express.json());

// Simulated database
const usersV1 = [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
];

const usersV2 = [
    { id: 1, fullName: 'Alice Johnson' },
    { id: 2, fullName: 'Bob Smith' }
];

// Version 1 of the API
app.get('/api/v1/users', (req, res) => {
    res.status(200).json(usersV1);
});

// Version 2 of the API
app.get('/api/v2/users', (req, res) => {
    res.status(200).json(usersV2);
});

// Handle 404 for unknown routes
app.use((req, res) => {
    res.status(404).json({ error: 'Not Found' });
});

// Start the server
app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
});

This example demonstrates API versioning using Express.js, a popular web framework for Node.js. The API has two versions: v1 and v2. In v1, the user data is structured with simple 'name' fields, while in v2, the user data includes a 'fullName' field to reflect a schema change. This showcases how versioning allows the API to evolve without breaking existing clients.

1. Clear Code Organization: The code MUST be organized into distinct routes for each version of the API, making it easy to maintain and extend. This separation ensures that changes in one version do not affect others.
2. Proper Error Handling: A 404 error handler MUST be included to respond with a clear error message if an unknown route is accessed, promoting better client-side error handling.
3. Best Practices: The API versions MUST be clearly defined in the URL path (e.g., '/api/v1/users' and '/api/v2/users'), which is a common and effective approach to versioning. This method allows clients to specify which version they want to interact with, maintaining backward compatibility.
4. Documentation: Each version's behavior MUST be documented, allowing clients to understand the differences and migration paths between versions.
5. Future-Proofing: By employing versioning from the start, the API MUST be designed to accommodate future changes and feature additions WITHOUT disrupting existing users, adhering to the principles of backward compatibility as outlined in the rule.

AI Interpretability Standards

{ "explicit_markers": { "description": "Clear markers for identifying requirements vs. suggestions", "requirements": [ "MUST use explicit directive terms 'MUST', 'SHOULD', and 'NEVER' to mark requirements and prohibitions", "MUST make 'MUST' statements identify absolute requirements", "MUST make 'SHOULD' statements identify recommended but optional behaviors", "MUST make 'NEVER' statements identify absolute prohibitions", "MUST position directive terms prominently at the beginning of requirement statements" ] }, "consistency": { "description": "Consistent application of directive terms", "requirements": [ "MUST use directive terms consistently throughout the entire rule", "MUST use the same directive term for the same level of requirement", "MUST NOT mix implied requirements with explicit requirements", "MUST maintain consistent formatting for all similar elements" ] }, "structure": { "description": "Structured organization of rule content", "requirements": [ "MUST organize rule content into clearly labeled sections", "MUST provide explicit metadata that an AI can extract", "MUST use consistent heading levels for similar content", "MUST separate directive statements into individual, distinct items for clear processing" ] } }

Clarity Requirements

{ "precision": { "description": "Precise, unambiguous language", "requirements": [ "MUST use specific, measurable terms rather than vague qualifiers", "MUST define any potentially ambiguous terms", "MUST provide explicit criteria for evaluating compliance", "MUST avoid terms with multiple potential interpretations" ] }, "completeness": { "description": "Complete coverage of requirements", "requirements": [ "MUST address both required and prohibited behaviors", "MUST specify handling of edge cases and exceptions", "MUST include scope and limitations of rule application", "MUST provide context for when the rule applies" ] }, "decision_support": { "description": "Information needed for AI decision-making", "requirements": [ "MUST provide clear decision criteria for the AI to apply", "MUST include prioritization guidance when multiple requirements may conflict", "MUST specify the relative importance of different aspects of the rule", "MUST provide guidance for explaining decisions to users" ] } }

Example Requirements

{ "demonstration": { "description": "Demonstrating rule application", "requirements": [ "MUST include examples showing correct rule application", "MUST annotate examples to highlight specific requirements being followed", "MUST provide contrasting examples of incorrect application when helpful", "MUST demonstrate common edge cases in examples" ] }, "explanation": { "description": "Explaining rule application", "requirements": [ "MUST explain how examples satisfy specific rule requirements", "MUST connect example components to explicit directive statements", "MUST highlight the reasoning behind important design decisions in examples", "MUST demonstrate how to explain compliance to users" ] } }

Metadata

<rule_meta> { "rule_id": "1230", "rule_name": "api-versioning", "rule_category": "Web and API Development Rules", "rule_type": "standard", "taxonomy": { "domain": "API Management", "subcategory": "Versioning" }, "version_history": [ {"version": "1.0.0", "date": "2023-06-15", "description": "Initial rule creation"}, {"version": "1.0.1", "date": "2023-10-01", "description": "Enhanced clarity and specificity of directives"} ] } </rule_meta>