search

StPfeffer / rusty-roads

A simple route manager application written in Rust
MIT License
0 stars 0 forks source link

Feature Request: Enhanced API Error Messages #71

Closed StPfeffer closed 1 month ago

StPfeffer commented 1 month ago

Summary

Implement enhanced error messaging for the API, providing more descriptive messages, meaningful error codes, and actionable hints to improve the developer experience and debugging process.

Background

The current API error messages are often vague, making it difficult for developers to understand the root cause of issues and how to resolve them. This can lead to increased debugging time and frustration. Improving the error messages with better descriptions, error codes, and hints will provide clearer guidance and improve overall API usability.

Objectives

  1. Descriptive Messages: Provide detailed error messages that clearly describe what went wrong.
  2. Meaningful Error Codes: Introduce a standardized set of error codes that developers can reference to quickly identify the type of error.
  3. Actionable Hints: Offer hints or suggestions on how to fix the issue, guiding developers towards a resolution.

Requirements

  1. Error Message Content

    • Clearly state what caused the error.
    • Provide context or specific details relevant to the error.

  2. Error Codes

    • Consistent error codes.

  3. Hints

    • Include suggestions on how to resolve the error.
    • Provide links to relevant documentation or resources if available.

Examples

Current Error Message:

{
  "status": "error",
  "message": "insert or update on table \"states\" violates foreign key constraint \"fk_states_country_id\""
}

Enhanced Error Message:

{
  "error": {
    "status": "error",
    "code": "404",
    "message": "The country with the provided ID does not exist in our records.",
    "hint": "Verify that the country ID is correct and exists in the database. Refer to the documentation for the list of valid country IDs or use the GET /countries endpoint to retrieve all available country IDs."
  }
}

Implementation Plan

  1. Audit Existing Errors: Review current error messages to identify areas for improvement.
  2. Define Error Codes: Establish a comprehensive list of error codes and descriptions.
  3. Update Error Handling Logic: Modify the API’s error handling mechanisms to generate the enhanced error messages.
  4. Documentation: Update API documentation to include a section on error codes, descriptions, and possible resolutions.
  5. Testing: Thoroughly test the new error messages to ensure clarity and usefulness.

Benefits

  1. Improved Developer Experience: Developers will find it easier to understand and resolve issues.
  2. Reduced Debugging Time: Clear and actionable error messages will speed up the debugging process.
  3. Enhanced Usability: Better error handling makes the API more user-friendly and robust.