### API Filtering Example Source: https://www.apiopscycles.com/resources/api-design-principles Illustrates how to use query parameters for filtering API resources, specifically showing a request to filter books by title and author. ```http GET /books?title=harry&author=rowling ``` -------------------------------- ### ISO 8601 Date and Time Format Example Source: https://www.apiopscycles.com/resources/api-design-principles Demonstrates the ISO 8601 format for date and time fields, including time zone information, as required for all date and time representations in API responses. ```json { "createdAt": "2024-12-21T10:00:00Z" } ``` -------------------------------- ### API Deprecation Notice Headers Source: https://www.apiopscycles.com/resources/api-design-principles Example of HTTP headers used to communicate deprecation notices for API endpoints. This includes a flag indicating deprecation, a sunset date, and a link to further details. ```http Deprecation: true Sunset: 2025-01-01 Link: ; rel="deprecation" ``` -------------------------------- ### Standardized Error Format Example Source: https://www.apiopscycles.com/resources/api-design-principles This JSON object demonstrates a standardized format for API error responses. It includes an error code, a human-readable message, and optional details for further clarification. This format aids developers in debugging by providing clear and consistent error information. ```json { "error": "invalid_request", "message": "The request is missing a required parameter.", "details": [ "Parameter 'user_id' is required." ] } ``` -------------------------------- ### Project Configuration (JSON) Source: https://www.apiopscycles.com/assets/resource/fr/Canvas_eventCanvas The main configuration file for the API Ops Cycles project, written in JSON. It defines the template, locale, metadata, and the structure of different event processing sections. This file dictates the overall workflow and event handling. ```json { "templateId": "eventCanvas", "locale": "fr-FR", "metadata": { "source": "", "license": "", "authors": [], "website": "" }, "sections": [ { "sectionId": "userTaskTrigger", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "inputEventPayload", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "processingLogic", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "outputEventResult", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] } ] } ``` -------------------------------- ### Project Configuration JSON Source: https://www.apiopscycles.com/assets/resource/pt/Canvas_eventCanvas This JSON object defines the overall configuration for the API Ops Cycles project. It specifies the template used for the event canvas, the locale for the application, and metadata related to the source, license, authors, and website. The 'sections' array further breaks down the configuration into distinct parts of the event processing flow. ```json { "templateId": "eventCanvas", "locale": "pt-BR", "metadata": { "source": "", "license": "", "authors": [], "website": "" }, "sections": [ { "sectionId": "userTaskTrigger", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "inputEventPayload", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "processingLogic", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "outputEventResult", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] } ] } ``` -------------------------------- ### JSON Configuration for Customer Journey Canvas Source: https://www.apiopscycles.com/assets/resource/fr/Canvas_customerJourneyCanvas This JSON object defines the structure for a customer journey canvas template. It specifies the template ID, locale, metadata such as source and license, and an array of sections, each with an ID and placeholder sticky notes. This configuration is essential for rendering the dynamic content of the customer journey. ```json { "templateId": "customerJourneyCanvas", "locale": "fr-FR", "metadata": { "source": "", "license": "", "authors": [], "website": "" }, "sections": [ { "sectionId": "customerDiscoversNeed", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "persona", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "pains", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "journeySteps", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "customerNeedIsResolved", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "gains", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "inputsOutputs", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] }, { "sectionId": "interactionProcessingRules", "stickyNotes": [ { "content": "Placeholder", "size": 80, "color": "#FFF399" } ] } ] } ``` -------------------------------- ### API Documentation Standards Source: https://www.apiopscycles.com/resources/api-design-principles Guidelines for generating comprehensive and user-friendly API documentation. ```APIDOC ## Documentation Generation ### Description APIs should be documented using the OpenAPI Specification (latest supported version). Documentation should be interactive and include examples for all endpoints to demonstrate request/response workflows. ### Maturity Levels - **Foundational**: Static documentation with examples. - **Growing**: Interactive, auto-generated documentation. - **Scaling**: Developer tools for API testing. - **Innovating**: Embedded developer environments for testing. ## Getting Started Section ### Description Provide a "Getting Started" section in the documentation to guide new users through authentication, common workflows, and testing endpoints. Use the Getting Started Guide Template as a reference. ## Sandbox Environment ### Description Offer a sandbox environment that mirrors production schemas and error codes for testing. Validate sandbox alignment through API audit tests. ## Naming Conventions ### Resource Naming - Use descriptive, industry-standard English terms for resource names (e.g., `books`, `users`, `loans`). - Avoid ambiguous terms like `type` or `status` without additional context. ### Attribute Naming - Use camelCase for attribute names (e.g., `userId`, `bookTitle`). - Avoid acronyms and abbreviations to ensure clarity. - Validate naming conventions during OpenAPI validation. ## Localization and Internationalization ### Accept Headers - Support localization using the `Accept-Language` header for API responses. - Provide localized strings and ensure all error messages can be translated. ### Date and Time Formats - Use ISO 8601 format for all date and time fields, including time zones. ```json { "createdAt": "2024-12-21T10:00:00Z" } ``` ### Testing Localization - Validate localized responses and error messages through functional tests. ## Versioning and Deprecation ### Versioning Strategy - Use semantic versioning (e.g., `/v1`, `/v2`) to indicate major changes. - Avoid breaking changes within a version. Deprecate old endpoints with sufficient notice. ### Deprecation Notices - Communicate deprecations through the Developer Portal and include headers in API responses: ```http Deprecation: true Sunset: 2025-01-01 Link: ; rel="deprecation" ``` ## Pagination and Filtering ### Pagination - Use standard pagination parameters: - `page`: Current page number. - `limit`: Number of items per page. ### Filtering - Allow filtering by common attributes (e.g., `title`, `author`, `genre`): ```http GET /books?title=harry&author=rowling ``` ### Testing Pagination and Filtering - Validate that pagination and filtering work as expected using API test cases. - **Maturity Levels**: - **Foundational**: Support basic pagination and filtering. - **Growing**: Ensure consistent behavior across endpoints. - **Scaling**: Optimize performance for large datasets. - **Innovating**: Intelligent filtering and predictive query support. ## Testing and Validation ### Automated Validation - Use tools like Spectral to validate OpenAPI specifications for completeness and consistency. ### Error Testing - Test error scenarios for all endpoints to ensure proper responses and actionable error messages. - **Maturity Levels**: - **Foundational**: Basic error handling for major scenarios. - **Growing**: Detailed error messages for all endpoints. - **Scaling**: Automated error validation using test tools. - **Innovating**: AI-driven insights for error patterns and predictions. ```