API & Mutation Engine

List endpoints support a rich filtering syntax that enables sophisticated data retrieval without custom endpoint logic. All standard list endpoints automatically support the following capabilities when they accept a QueryFilters parameter:

Providing pageSize and pageIndex parameters applies pagination to the result set. The page index is 0-based, so the first page is index 0.

GET /products/product?pageSize=12&pageIndex=0

Returns the first page of 12 products. To retrieve the second page, use pageIndex=1.

Exact Matching

Providing a query parameter whose name exactly matches a database column (case-insensitive) will attempt to match the value exactly.

GET /products/product?typeId=GENERAL

Returns only products whose TypeId column is "GENERAL".

Multi-Matching

Providing multiple instances of the same query parameter key matches against any of the provided values (OR logic).

GET /products/product?id=1&id=2&id=3

Returns products with IDs 1, 2, and 3.

String Comparison

Querying against string properties supports comparisons via StartsWith, EndsWith, or Contains suffixes appended to the column name.

GET /products/product?nameStartsWith=laser

Returns all products whose Name column begins with "laser".

Range Matching

For any range-comparable column (numerical types, dates, etc.), you can provide a Min and/or Max suffix to search against ranges of data.

GET /products/product?updatedDateMin=2024-11-28T00:00:00

Returns all products updated since the provided date.

Collection Queries

Basic querying against collections is supported using Any, All, and Count operators. Any queries support string comparison and multi-matching. Count queries support range matching.

GET /products/product?categoriesAnyPrimaryId=5

Returns all products that are assigned to Category ID 5.

Tag Matching

For records that support tags, you can query against tag values using the tags. prefix. Multi-matching across tag keys is fully supported.

GET /products/product?tags.color=red&tags.size=large

Matches any product whose Tags JSON contains a color tag of "red" and a size tag of "large".

All of the query operations described above support inversion by prefixing the query parameter with Not (case-insensitive). This inverts the filter logic, excluding matching records instead of including them.

GET /products/product?notNameStartsWith=laser

GET /products/product?notTags.color=blue

GET /products/product?notTags.color=

By default, list and single-get endpoints return only the properties of the base entity itself. The include parameter allows you to request any nested objects to be populated in the response.

GET /products/product

{
  "Id": 1,
  "Key": "Sample",
  "Categories": [],
  "Prices": []
}

GET /products/product?include=Categories

{
  "Id": 1,
  "Key": "Sample",
  "Categories": [
    {
      "Id": 1,
      "PrimaryId": 5,
      "SecondaryId": 1
    }
  ],
  "Prices": []
}

GET /products/product?include=Categories.Primary&include=Prices.Currency

{
  "Id": 1,
  "Key": "Sample",
  "Categories": [
    {
      "Id": 1,
      "PrimaryId": 5,
      "Primary": {
        "Id": 5,
        "Key": "CATEGORY-KEY",
        "ParentId": 3,
        "Name": "Electronics"
      },
      "SecondaryId": 1
    }
  ],
  "Prices": [
    {
      "Id": 1,
      "Price": 5,
      "CurrencyId": 1,
      "Currency": {
        "Id": 1,
        "Key": "USD",
        "Name": "United States Dollar",
        "Symbol": "$"
      }
    }
  ]
}

Sort query results by passing a sort parameter in the format sort.column=asc|desc. Multiple sort parameters are applied in the order they appear in the query string, enabling multi-level sorting.

GET /products/product?sort.name=asc

GET /products/product?sort.typeid=desc&sort.name=asc

api.ListLogEntry({
    PageIndex: 0,
    PageSize: 16,
    "Sort.LoggedAt": "desc",
    ...Object.fromEntries(params),
})

The mutation engine handles all create, update, upsert, and delete operations for entities via the API. It enables partial object patching, meaning you only need to supply the properties you intend to change. Each object supplied to the mutator should contain an identifier (Key or Id), the properties to update, and optionally an operation hint.

{
    "$op": "update",
    "Key": "SKU-OF-PRODUCT",
    "Name": "New Name"
}

[
    {
        "$op": "update",
        "Key": "SKU-OF-PRODUCT",
        "Name": "New Name"
    },
    {
        "$op": "update",
        "Key": "OTHER-SKU",
        "Name": "Different New Name",
        "Description": "A new description on this one"
    }
]

The mutation engine supports updating related and associated records within a single payload. This reduces round trips to and from the API, which by extension reduces round trips to the database. Each nested object follows the same mutation rules, including independent operation hints.

{
    "Key": "DEALER-1",
    "TaxExemptionNumber": "ABC123",
    "CustomerContacts": [
        {
            "$op": "update",
            "Key": "DEALER-1-ADDR-1",
            "IsActive": false
        },
        {
            "$op": "create",
            "Key": "DEALER-1-ADDR-3",
            "Name": "LA Warehouse",
            "Secondary": {
                "$op": "create",
                "Key": "DEALER-1-ADDR-3",
                "Street1": "123 Warehouse St."
            }
        }
    ]
}

Directly set the foreign key property if you are certain of the identifier. Bypasses all lookups and validation in the mutation engine. If the key does not exist in the target table, you will get a foreign key constraint error.

{
    "Key": "Some Customer",
    "TypeId": "Customer"
}

Provide a value to the navigation property (not the FK property) and the mutation engine runs a lookup. Lookups are internally cached, so repeat calls for the same data in a single run are fairly quick. Returns an error if the key/ID does not resolve.

{
    "Key": "ORDER-123",
    "Items": [
        {
            "$op": "create",
            "Key": "ITEM-1",
            "Product": "SOME-PRODUCT-SKU"
        },
        {
            "$op": "create",
            "Key": "ITEM-2",
            "Product": 123
        }
    ]
}

Provide an object with exclusively an identifier. The nested object goes through the full mutation process: check operation (defaults to upsert), pick the identifier, see if it resolves, and if not, create a new record. This ensures the related object exists but comes at a higher performance cost.

{
    "Key": "ORDER-123",
    "Items": [
        {
            "$op": "create",
            "Key": "ITEM-1",
            "Product": { "Key": "SOME-PRODUCT-SKU" },
            "Type": { "Key": "LocalTax" }
        }
    ]
}

star Controllers (Preferred)

Controllers are the preferred method of creating endpoints. Define a class marked with the [ApiController] attribute and derive from PhoenixController.

[ApiController]
public class SampleController : PhoenixController
{
    [HttpGet]
    [Route("/sample", Name = nameof(GetModel))]
    public async Task<ActionResult<SomeModel>> GetModel()
    {
        // ...
    }
}

// Request body
[HttpPost]
[Route("/sample/with-body")]
public async Task<ActionResult<SomeModel>> SomeAction(
    [FromBody] SomeModel input) { }

// Route parameter
[HttpGet]
[Route("/sample/{id}")]
public async Task<ActionResult<SomeModel>> GetById(
    [FromRoute] int id) { }

// Query parameter
[HttpGet]
[Route("/sample/with-query")]
public async Task<ActionResult<SomeModel>> Get(
    [FromQuery] string value) { }

// Dependency injection
[HttpGet]
[Route("/sample/with-injection")]
public async Task<ActionResult<SomeModel>> GetSomething(
    [FromServices] IPipelineContext context) { }

[HttpGet]
[Route("list-some-data")]
public async Task<ActionResult<List<SomeModel>>> ListSomeData(
    QueryFilters query,
    [FromServices] IPipelineContext context)
{
    return await ListModelsPipeline<SomeEntity, SomeModel>
        .ExecuteAsync(query, context);
}

Minimal API (alternative)

Minimal APIs should only be used if the Controller approach is not feasible (such as generic endpoint controllers). Configure them via the OnStartup hook in your plugin file.

public class MyPlugin : Plugin
{
    public override void OnStartup(WebApplication app)
    {
        app.MapGet("/sample/minimal-api", () => "Hello!");

        app.MapGet("/sample/{id}",
            ([FromRoute] int id) => /* ... */);

        app.MapPost("/sample",
            async ([FromServices] IPipelineContext context) =>
        {
            // Do stuff
        });
    }
}

PhoenixController configures all endpoints to require at least being logged in by default. You can customize access control with the following attributes.

[HttpGet]
[Route("/secure/route")]
[Authorize(Roles = "Global Admin")]
public async Task<ActionResult<SomeSecureData>> Get()
{
    // ...
}

[HttpPost]
[Route("/secure/create")]
[PermissionAuthorize("Schema.Table.C")]
public async Task<ActionResult<SomeSecureData>> Create()
{
    // ...
}