Breaking Changes #

• Renamed package json_api_client to op_rest_api_client

  • Update all import statements:

    // No longer valid:
    import 'package:json_api_client/json_api_client.dart'; 
    // Use this instead:
    import 'package:op_rest_api_client/op_rest_api_client.dart'; 
    

  • Update pubspec.yaml dependencies:

    dependencies:
      op_rest_api_client: ^0.13.0
    

Breaking Changes #

• Renamed ApiOpResult to OpResult for consistency with the package naming convention.
• Renamed OpResultError to OpError to simplify error handling terminology.
• Renamed ApiOpResultErrorType to ApiErrorType to better reflect its role as an API-specific error type.

These changes require updating all references to the renamed classes in your codebase.

Upgrades & Improvements #

• Upgraded to the latest op_result library:
• Refactored codebase to align with op_result changes:
  • Updated all failure() calls to use the new factory constructor.
  • Ensured compliance with the new multiple error handling system.

New Features #

• Added Support for PUT, PATCH, and DELETE Methods

  • The API client now supports all major HTTP request methods, including:

    • sendPut()
    • sendPatch()
    • sendDelete()

  • These methods function similarly to sendPost(), allowing request bodies and encoded data.

  • Usage Examples:

    // PUT Request
    final response = await apiClient.sendPut(
      apiEndPoint: ApiEndpoints.updateUser,
      identity: userIdentity,
      body: {"name": "Updated Name", "email": "[email protected]"},
    );
    
    // PATCH Request
    final response = await apiClient.sendPatch(
      apiEndPoint: ApiEndpoints.partialUpdate,
      identity: userIdentity,
      body: {"status": "active"},
    );
    
    // DELETE Request
    final response = await apiClient.sendDelete(
      apiEndPoint: ApiEndpoints.deleteAccount,
      identity: userIdentity,
    );
    

• Enhanced API Consistency

  • The API client now follows a unified request structure for POST, PUT, PATCH, and DELETE, ensuring consistent handling of request bodies.
  • body and encodedBody work the same way across all methods.

• Updated Documentation & Macros

  • The DartDoc macros now clarify that:
    • body is optional for DELETE requests.
    • headers["authorization"] cannot be used together with identity, but other headers can be combined.

Enhancements #

• Added Support for x-www-form-urlencoded Request Body Encoding

  • The API client now supports sending requests using application/x-www-form-urlencoded.
  • If encodedBody is provided, it takes precedence over body, ensuring full control over pre-encoded data.
  • If encodedBody is null, the client automatically encodes body based on the content-type header.
  • Encoding behavior:
    • "application/json" (default) → Encoded as JSON.
    • "application/x-www-form-urlencoded" → Encoded as a query string.
  • Example Usage:

    final response = await apiClient.sendPost(
      apiEndPoint: ApiEndpoints.login,
      identity: null,
      body: {"email": "[email protected]", "password": "123456"},
    ); // Defaults to JSON encoding
    

    final response = await apiClient.sendPost(
      apiEndPoint: ApiEndpoints.login,
      identity: null,
      headers: {"content-type": "application/x-www-form-urlencoded"},
      body: {"email": "[email protected]", "password": "123456"},
    ); // Automatically encodes as form-urlencoded
    

    final response = await apiClient.sendPost(
      apiEndPoint: ApiEndpoints.login,
      identity: null,
      encodedBody: "email=user%40example.com&password=123456",
      headers: {"content-type": "application/x-www-form-urlencoded"},
    ); // Uses pre-encoded body
    

• New Public Helper: restApiBodyEncoder

  • The package now exports restApiBodyEncoder, a utility function to encode request bodies according to the content-type.
  • Users can use this function if they need to manually encode a request body before passing it to encodedBody.
  • Example Usage:

    import 'package:rest_api_client/rest_api_client.dart';
    
    final String encoded = restApiBodyEncoder(
      {"email": "[email protected]", "password": "123456"},
      "application/x-www-form-urlencoded",
    )!;
    
    print(encoded); // Output: email=user%40example.com&password=123456
    

  • This allows consistency between manual encoding and the library's automatic encoding logic.

• Updated sendPost Documentation

  • Clarified that body is encoded based on the content-type header, defaulting to application/json.
  • Explicitly documented that encodedBody takes precedence if provided.
  • Improved examples for JSON, form-urlencoded, and manually encoded bodies.

Breaking Changes #

• Renamed rawToken to identityData

  • This change makes the field name more representative of its purpose, indicating that it holds identity-related authentication data rather than just a raw token.
  • Migration Guide:
    • Update all instances of rawToken to identityData.
  • Example:

    final AuthIdentity identity = ...;
    print(identity.rawToken); // No longer valid
    print(identity.identityData); // Use this instead
    

• Renamed authToken() to authorizationHeader()

  • This change clarifies that the method returns a properly formatted HTTP Authorization header instead of just a raw token.
  • Migration Guide:
    • Replace calls to authToken() with authorizationHeader().
  • Example:

    final Identity identity = ...;
    final String token = identity.authToken(); // ❌ No longer valid
    final String header = identity.authorizationHeader(); // ✅ Use this instead
    

Enhancements #

• Improved naming conventions for better clarity and maintainability.
• Strengthened the API client's consistency in handling authentication.

Migration Notes #

• All implementations of Identity<T> must update their method signatures to reflect the new names.
• If using authToken() in API request headers, replace it with authorizationHeader().
• If storing rawToken, update it to identityData.

Added #

• Support for Token Refresh:

  • The API client now supports automatic token refresh, ensuring persistent authentication without requiring the user to log in again when their access token expires.
  • When an API request fails with 401 Unauthorized, the client will attempt a token refresh once before retrying the request.
  • If the refresh is successful, the request is retried seamlessly using the new access token.

• refresh Method in Identity:

  • This new method is responsible for invoking the refresh token flow.
  • It is automatically triggered when the access token is expired or when a 401 response is received from the API.

Fixes & Improvements #

• Optimized API request handling to automatically retry requests after a successful token refresh.

Breaking Changes #

• Removed authHeaderKey parameter
  • If needed, custom authorization headers can now be passed directly through the headers parameter in each API call.
  • As a result, when identity is specified in a request, the Authorization header now defaults to 'Bearer $token'.

Enhancements #

• Flexible Authentication Handling
  • Both headers and identity can now be provided in a request.
  • However, headers['Authorization'] and identity are mutually exclusive—if headers['Authorization'] is explicitly set, identity will be ignored.

Added #

• Added support for custom headers in OpRestApiClient.
  • Users can now pass an optional headers parameter in API requests, allowing full control over authentication and custom headers.
  • If headers is provided, identity is ignored, making the library independent of the Identity class and more flexible for various authentication methods.
  • This enables the use of API keys, session-based auth, and other custom headers without modifying the core API client.

Added #

• Added support for an optional onUnauthenticated callback in OpRestApiClient. This callback is triggered when a request returns an unauthenticated error, enabling custom handling of unauthenticated states, such as logging out or displaying a user message.
• The onUnauthenticated callback supports both synchronous and asynchronous functions, allowing flexibility for diverse use cases.

Added #

• Introduced authToken() in Identity, providing a method to retrieve the authentication token regardless of the type T of the Identity. This enhances flexibility and ensures a consistent way to access tokens in various implementations.
• Renamed token in Identity to rawToken to better distinguish it from the authToken() method, which provides a processed or extracted authentication token.

Added #

• Made Identity a generic class, enabling the usage of tokens with types other than String. This increases flexibility and allows for better type safety in applications that use custom token types.

Added #

• Introduced an endpoints enum to map API endpoints and validate time. This improves maintainability and consistency when working with API endpoint definitions.

Initial Release #

• Initial release with core functionality to interact with APIs, including support for basic CRUD operations.