Data-Coupler/DataConnection/REST/Interfaces/IRestServiceClient.cs

using System.Collections.Generic;
using System.Threading.Tasks;
using System.Threading;

namespace DataConnection.REST.Interfaces
{
    /// <summary>
    /// Interface for a generic REST service client.
    /// </summary>
    public interface IRestServiceClient
    {
        /// <summary>
        /// Authenticates the client using the provided credentials.
        /// Implementation varies by service type.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>True if authentication was successful, false otherwise.</returns>
        Task<bool> AuthenticateAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Sends a GET request to the specified URI.
        /// </summary>
        /// <typeparam name="T">The type of the object to deserialize the response content to.</typeparam>
        /// <param name="requestUri">The URI the request is sent to.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The deserialized response content.</returns>
        Task<T?> GetAsync<T>(string requestUri, CancellationToken cancellationToken = default);

        /// <summary>
        /// Sends a POST request to the specified URI.
        /// </summary>
        /// <typeparam name="TRequest">The type of the request object.</typeparam>
        /// <typeparam name="TResponse">The type of the object to deserialize the response content to.</typeparam>
        /// <param name="requestUri">The URI the request is sent to.</param>
        /// <param name="payload">The HTTP request content sent to the server.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The deserialized response content.</returns>
        Task<TResponse?> PostAsync<TRequest, TResponse>(string requestUri, TRequest payload, CancellationToken cancellationToken = default);        /// <summary>
        /// Creates a new entity by sending a POST request with the provided data.
        /// </summary>
        /// <param name="entityName">The name of the entity to create.</param>
        /// <param name="entityData">The data for the new entity as key-value pairs.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The created entity data or null if creation failed.</returns>
        Task<Dictionary<string, object>?> CreateEntityAsync(string entityName, Dictionary<string, object> entityData, CancellationToken cancellationToken = default);        /// <summary>
        /// Creates a new entity or updates an existing one (upsert operation).
        /// </summary>
        /// <param name="entityName">The name of the entity to upsert.</param>
        /// <param name="entityData">The data for the entity as key-value pairs.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The upserted entity data or null if operation failed.</returns>
        Task<Dictionary<string, object>?> UpsertEntityAsync(string entityName, Dictionary<string, object> entityData, CancellationToken cancellationToken = default);

        /// <summary>
        /// Searches for entities matching the specified key fields.
        /// </summary>
        /// <param name="entityName">The name of the entity to search.</param>
        /// <param name="keyFields">The key fields and their values to search for.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A list of matching entities.</returns>
        Task<List<Dictionary<string, object>>> FindEntitiesByKeysAsync(string entityName, Dictionary<string, object> keyFields, CancellationToken cancellationToken = default);

        /// <summary>
        /// Deletes an entity by its ID or unique identifier.
        /// </summary>
        /// <param name="entityName">The name of the entity to delete.</param>
        /// <param name="entityId">The ID or unique identifier of the entity to delete.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>True if deletion was successful, false otherwise.</returns>
        Task<bool> DeleteEntityAsync(string entityName, string entityId, CancellationToken cancellationToken = default);        /// <summary>
        /// Updates an existing entity by its ID with the provided data.
        /// </summary>
        /// <param name="entityName">The name of the entity to update.</param>
        /// <param name="entityId">The ID or unique identifier of the entity to update.</param>
        /// <param name="entityData">The data to update as key-value pairs.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>The updated entity data or null if update failed.</returns>
        Task<Dictionary<string, object>?> UpdateEntityAsync(string entityName, string entityId, Dictionary<string, object> entityData, CancellationToken cancellationToken = default);

        /// <summary>
        /// Searches for entities matching the specified required fields to detect duplicates.
        /// </summary>
        /// <param name="entityName">The name of the entity to search.</param>
        /// <param name="requiredFields">The required fields and their values to search for.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A list of matching entities.</returns>
        Task<List<Dictionary<string, object>>> FindEntitiesByRequiredFieldsAsync(string entityName, Dictionary<string, object> requiredFields, CancellationToken cancellationToken = default);

        // Add other methods as needed (PUT, DELETE, PATCH, etc.)
        // Consider adding methods for handling raw HttpResponseMessage or string responses
    }
}