Introduction

This guide shows how to connect your .NET application to a RESTful Web API using Flux.REST.

Installation

Install the Flux.REST NuGet package:

dotnet add package BitzArt.Flux.Rest

Get Started

Example Web API

Consider the following example Web API that manages courses and students. In Flux.REST, each resource is represented by an abstraction called Set.

Courses Set

{
  "Id": 1,
  "Title": "Introduction to Biology"
}

Students Set

{
  "Id": 1,
  "Name": "Alice"
}

Note

Notice that Students can be fetched by ID of a Course they participate in.

Configuration

Add respective model classes to match the API’s resources:

public class Course
{
    public int? Id { get; set; }
    public string? Title { get; set; }
}

public class Student
{
    public int? Id { get; set; }
    public string? Name { get; set; }
}

Configure Flux and the Course and Student Sets:

services.AddFlux(flux =>
{
    flux.AddService("school-api")
        .UsingRest("https://school-api.example.com")
        .AddSet<Course, int>()
            .WithEndpoint("courses")
        .AddSet<Student, int>()
            .WithEndpoint("students")
            .WithGet((PageRequest _) => "courses/{{courseId}}/students");
});

• AddFlux registers the Flux Context in the DI container.
• AddService("school-api") registers a Flux Service named school-api in the DI container.
• UsingRest configures the Service to use REST and sets its base URL.
• AddSet<Course, int> registers a set for the Course resourse.
  • WithEndpoint("courses") configures "courses" base endpoint path for all Course Set operations.
• AddSet<Student, int> registers a set for the Student resourse.
  • WithEndpoint("students") configures "students" base endpoint path for all Student Set operations.
  • WithGet((PageRequest _) => ...) sets the path for Get Page operation. It will take precedence over WithEndpoint("students") configuration for this operation.

Tip

For advanced endpoint configuration and precedence rules, see Endpoint Configuration.

Resolve Services

Inject Set Contexts to work with set data:

public class SchoolService(
    IFluxSetContext<Course> courseSetContext,
    IFluxSetContext<Student> studentSetContext)
{
}

Work with Sets

Courses

Use the injected courseSetContext to run Course operations:

// [GET] https://school-api.example.com/courses?offset=0&limit=20
var coursesPage = await courseSetContext.GetPageAsync(offset: 0, limit: 20);

// [GET] https://school-api.example.com/courses/{courseId}
var course = await courseSetContext.GetAsync(courseId);

// [POST] https://school-api.example.com/courses
await courseSetContext.AddAsync(newCourse);

// [DELETE] https://school-api.example.com/courses/{courseId}
await courseSetContext.RemoveAsync(courseId);

Flux.REST sends the corresponding HTTP requests shown in the Course endpoints table.

Students

The Student Get Page path contains {courseId}. Pass its value as a named operation parameter when you call studentSetContext.GetPageAsync:

var parameters = new OperationParameterCollection(
    new List<KeyValuePair<string, object>>
    {
        new("courseId", 42)
    });

// [GET] https://school-api.example.com/courses/42/students?offset=0&limit=20
var studentsPage = await studentSetContext.GetPageAsync(
    offset: 0,
    limit: 20,
    parameters: parameters);

Pagination

Important

Configurable pagination is currently a work-in-progress.