API Service Interface

IApiService.cs

/// <summary>
/// By adhering to this interface, services will align to all the common HTTP methods and will expose sync and async versions.
/// </summary>
/// <typeparam name="TModel">The type of model that the SQL entity will be bound to. Can be decorated.</typeparam>
/// <typeparam name="TKey">The type of primary key of the model (primitive). Can be decorated.</typeparam>
public interface IApiService<TModel, in TKey> : IApiServiceSync<TModel, TKey>, IApiServiceAsync<TModel, TKey> {}

/// <summary>
/// By adhering to this interface, services will align to all the common HTTP methods and expose sync versions.
/// </summary>
/// <typeparam name="TModel">The type of model that the SQL entity will be bound to. Can be decorated.</typeparam>
/// <typeparam name="TKey">The type of primary key of the model (primitive). Can be decorated.</typeparam>
public interface IApiServiceSync<TModel, in TKey> {
    /// <summary>
    /// Get a set of entities based on dapper param (or DynamicParameters) constraints.
    /// </summary>
    /// <param name="param">The dapper param (or DynamicParameters) constraints.</param>
    /// <param name="top">The max number of records to return.</param>
    /// <returns>A set of entities bound to the model.</returns>
    IEnumerable<TModel> Get(object param = null, int top = 500);

    /// <summary>
    /// Get a single entity by primary key or throw if 0 or multiple matches appear for primary key.
    /// </summary>
    /// <param name="id">The id to match for the primary key.</param>
    /// <returns>The returned entity as TModel.</returns>
    TModel GetOne(TKey id);

    // Get first entity match by specified parameter match.
    TModel GetFirst<TColumn>(TColumn value);

    // Get first entity match by specified parameter match.
    IEnumerable<TModel> GetTop<TColumn>(TColumn value, int top = 500);

    // Upsert resource
    TModel Put(TModel entity);

    // Create resource
    TModel Post(TModel entity);

    // Delete resource
    bool Delete(TKey id);
}

/// <summary>
/// By adhering to this interface, services will align to all the common HTTP methods and expose async versions.
/// </summary>
/// <typeparam name="TModel">The type of model that the SQL entity will be bound to. Can be decorated.</typeparam>
/// <typeparam name="TKey">The type of primary key of the model (primitive). Can be decorated.</typeparam>
public interface IApiServiceAsync<TModel, in TKey> {
    /// <summary>
    /// Get a set of entities based on dapper param (or DynamicParameters) constraints.
    /// </summary>
    /// <param name="param">The dapper param (or DynamicParameters) constraints.</param>
    /// <param name="top"></param>
    /// <returns>A set of entities bound to the model.</returns>
    Task<IList<TModel>> GetAsync(object param = null, int top = 500);

    /// <summary>
    /// Get a single entity by primary key or throw if 0 or multiple matches appear for primary key.
    /// </summary>
    /// <param name="id">The id to match for the primary key.</param>
    /// <returns>The returned entity as TModel.</returns>
    Task<TModel> GetOneAsync(TKey id);

    // Get first entity match by specified parameter match.
    Task<TModel> GetFirstAsync<TColumn>(TColumn value);

    // Get first entity match by specified parameter match.
    Task<IList<TModel>> GetTopAsync<TColumn>(TColumn value, int top = 500);

    // Upsert resource
    Task<TModel> PutAsync(TModel entity);

    // Create resource
    Task<TModel> PostAsync(TModel entity);

    // Delete resource
    Task<bool> DeleteAsync(TKey id);
}