using DataConnection.REST.Models;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace DataConnection.REST.Interfaces
{
    /// <summary>
    /// Interface for discovering metadata (entities, properties) from a REST service.
    /// </summary>
    public interface IRestMetadataDiscovery
    {
        /// <summary>
        /// Discovers a list of available entities from the REST service without detailed field information.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A list of discovered entity summaries.</returns>
        Task<List<RestEntitySummary>> DiscoverEntitySummariesAsync(CancellationToken cancellationToken = default);

        /// <summary>
        /// Discovers detailed information for a specific entity including all its properties.
        /// </summary>
        /// <param name="entityName">The name of the entity to get details for.</param>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>Detailed entity information or null if not found.</returns>
        Task<RestEntityInfo?> DiscoverEntityDetailsAsync(string entityName, CancellationToken cancellationToken = default);

        /// <summary>
        /// Discovers entities and their properties from the REST service metadata.
        /// </summary>
        /// <param name="cancellationToken">Cancellation token.</param>
        /// <returns>A list of discovered entity information.</returns>
        Task<List<RestEntityInfo>> DiscoverEntitiesAsync(CancellationToken cancellationToken = default);
    }
}