AutoBackend.SDK 0.1.9

AutoBackend

DEVELOPER BUILDS	RELEASE BUILDS

This package provides infrastructure templates for facilitating the creation of backend services. It is a personal project without a commercial foundation and offers no guarantees regarding future development.

Features

• Database
  • Schema Modeling
    • Keyless Entities
    • Single-PK Entities
    • Multi-PK Entities
  • Providers
  • Migrations
    • Migrate on Startup
• API
  • HTTP API
  • GraphQL
    • Queries
    • Mutations
  • Modeling
  • Filtering
  • Authorization: currently unsupported (may be introduced in future releases)

Initialization

A sample usage scenario is available here. Copies of those samples are also provided.

Initialize AutoBackend from your Program.cs file

using AutoBackend.Sdk;

await new AutoBackendHost<Program>().RunAsync(args);

Define models to represent your domain relationships

Refer to the sample project models for examples.

public class Budget
{
    public Guid Id { get; set; }
    
    //..
}

public class Transaction
{
    public Guid Id { get; set; }
    
    //..
}

public class TransactionVersion
{
    //..
}

public class User
{
    public long Id { get; set; }
    
    //..
}

public class Participating
{
    public long UserId { get; set; }
    
    public Guid BudgetId { get; set; }
    
    //..
}

Configuration of all features is detailed below

Database

Currently supported relational databases (including in-memory) are:

• SqlServer
• Postgres

AutoBackend.SDK will generate tables and establish relationships for your configured entities.

Schema Modeling

There are typically three types of database tables:

• Keyless,
• Single-column primary key,
• Multi-column primary key.

Depending on the number of columns in your entity, follow the instructions below to enable AutoBackend.SDK to track changes.

Keyless Entities

Use the [GenericEntity] attribute to designate a model as a keyless entity.

[GenericEntity]
public class TransactionVersion
{
    //...
}

Single-PK Entities

Use the [GenericEntity(<primary key property name>)] attribute to designate a model as an entity with a single property primary key.

[GenericEntity(
    nameof(Id)
)]
public class Budget
{
    public Guid Id { get; set; }

    // ...
}

Multi-PK Entities

Use the [GenericEntity(<primary key property names>)] attribute to designate a model as an entity with a composite primary key.

Currently, the maximum number of properties in a composite key is 8.

It is anticipated that this limit will suffice for most use cases.

[GenericEntity(
    nameof(UserId),
    nameof(BudgetId)
)]
public class Participating
{
    public long UserId { get; set; }

    public Guid BudgetId { get; set; }
    
    // ...
}

Providers

For database connection management, configure the "Database" section.

"Database": {
  "PrimaryProvider": "InMemory",
  "Providers": {
    "InMemory": "InMemory database name",
    "SqlServer": "SqlServer database connection string",
    "Postgres": "Postgres database connection string"
  }
}

The PrimaryProvider property accepts one of the following string values:

• InMemory,
• SqlServer,
• Postgres.

The Providers property must contain an object with optional properties: InMemory, SqlServer, or Postgres. The property corresponding to the chosen PrimaryProvider value is mandatory.

Migrations

First, install Entity Framework Core Tools. You can create a new migration with one of the following commands executed from the project root directory.

dotnet ef migrations add "<your migration name>" -o Migrations/SqlServer -c SqlServerGenericDbContext for SqlServer.

dotnet ef migrations add "<your migration name>" -o Migrations/Postgres -c PostgresGenericDbContext for Postgres.

Alternatively, use scripts to add a new migration or to remove the last migration for both database providers.

If you opt not to have AutoBackend manage database migrations (see above), you can perform migrations manually by executing dotnet ef database update from the project root directory.

Migrate on Startup

If using a relational database (e.g., SqlServer or Postgres), you can configure AutoBackend to either automatically migrate the database at application startup or not, by passing the migrateRelationalOnStartup parameter to the RunAsync method where AutoBackend is initialized. For example:

await new AutoBackend.Sdk.AutoBackendHost<Program>().RunAsync(args, migrateRelationalOnStartup: true);

API

AutoBackend.SDK currently supports two types of application interfaces:

• Traditional HTTP API
• Basic GraphQL

HTTP API

Use the [GenericController] attribute on models to generate HTTP API endpoints by AutoBackend.

❗Disclaimer

The [GenericController] attribute is compatible only with models also marked with [GenericEntity].

Response Container and Endpoints

The current and only API version is v1. API v1 supports JSON and uses the following response container format:

{
  "ok": boolean,
  "error_code": number,
  "description": string,
  "request_time_ms": number,
  "result": <response object>
}

For detailed information on generated endpoints, access /swagger.

Endpoints

The [GenericController] attribute generates the following HTTP API endpoints:

📘Filtering Capabilities

Refer to the following section for more information on filtering.

Code Samples

[GenericEntity(
    nameof(Id)
)]
[GenericController]
public class User
{
    public long Id { get; set; }

    // ...
}

GraphQL

Use the [GenericGqlQuery] and [GenericGqlMutation] attributes on models to generate GraphQL queries and * mutations*, respectively.

❗Disclaimer

The [GenericGqlQuery] and [GenericGqlMutation] attributes are compatible only with models also marked with [GenericEntity].

For detailed information on generated queries and mutations, access /graphql.

Queries

The [GenericGqlQuery] attribute generates the following GraphQL queries:

📘Filtering Capabilities

Refer to the following section for more information on filtering.

Code Samples

[GenericEntity(
    nameof(Id)
)]
[GenericGqlQuery]
public class User
{
    public long Id { get; set; }

    // ...
}

Mutations

The [GenericGqlMutation] attribute generates the following GraphQL mutations:

Code Samples

[GenericEntity(
    nameof(Id)
)]
[GenericGqlMutation]
public class User
{
    public long Id { get; set; }

    // ...
}

Modeling

AutoBackend.SDK generates request and response models for any entity with configured HTTP API or GraphQL generation. These models include all original entity properties, unless specific properties are explicitly included in request or response models, in which case non-specified properties will be omitted.

Request Models

The [GenericRequest] attribute defines which properties are permitted for reflection from the request model to the entity.

Code Samples

[GenericEntity(
    nameof(Id)
)]
[GenericController]
[GenericGqlQuery]
[GenericGqlMutation]
[GenericRequest(
    nameof(Id),
    nameof(UserId),
    nameof(BudgetId),
    nameof(Amount),
    nameof(DateTimeUtc),
    nameof(Comment),
    nameof(SecretKey)
)]
public class Transaction
{
    // ...
}

Response Models

The [GenericResponse] attribute defines which properties are permitted for reflection from the response model to the entity.

Code Samples

[GenericEntity(
    nameof(Id)
)]
[GenericController]
[GenericGqlQuery]
[GenericGqlMutation]
[GenericResponse(
    nameof(Id),
    nameof(UserId),
    nameof(BudgetId),
    nameof(Amount),
    nameof(DateTimeUtc),
    nameof(Comment)
)]
public class Transaction
{
    // ...
}

Filtering

AutoBackend.SDK generates filter models for any entity with configured HTTP API or GraphQL generation. By default, these models include only pagination management properties. To include specific entity properties in the filter model, use the [GenericFilter] attribute.

Defaults

By default, two filter parameters are always available for any GET request (returning a list of entities) or GraphQL queries, to manage pagination:

• skipCount: number
• takeCount: number

Generic

The [GenericFilter] attribute designates a model property as filterable in the generated entity.

[GenericEntity(
    nameof(Id)
)]
[GenericController]
[GenericGqlQuery]
[GenericGqlMutation]
public class Budget
{
    [GenericFilter]
    public Guid Id { get; set; }

    [GenericFilter]
    public string Name { get; set; }

    [GenericFilter]
    public long? OwnerId { get; set; }

    // ...
}

Consequently, AutoBackend will construct a filter model with parameters that can be utilized in API endpoints like /api/v1/<model name> or /api/v1/<model name>/count, and in GraphQL queries.

• API filter parameter names are generated following the pattern: <property's camelCase-name>.<condition name>.
• GraphQL queries will have filtering models with condition properties generated.

The following conditions are supported: equal, notEqual, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, in, isNull, equal.