Skip to content

developer.md

Latest commit

 

History

History
256 lines (197 loc) · 11.5 KB

developer.md

File metadata and controls

256 lines (197 loc) · 11.5 KB

Admin API Developer Instructions

Contents

Development Pre-Requisites

Note: For quick, machine-friendly guidance and short rules, consult the repository root AGENTS.md (sections: General, Coding & Tests, Run & Architecture). Use docs/developer.md for full procedures and examples.

Build Script

The PowerShell script build.ps1 in the root directory contains functions for running standard build operations at the command line. This script assumes that .NET 10.0 SDK or newer is installed. Other dependency tools are downloaded as needed (NuGet, NUnit).

Available commands (e.g., ./build.ps1 clean) (commands are not case sensitive):

  • clean: runs dotnet clean
  • build: runs dotnet build with several implicit steps (clean, restore, inject version information).
  • unitTest: executes NUnit tests in projects named *.UnitTests, which do not connect to a database.
  • integrationTest: executes NUnit tests in projects named *.Test, which connect to a database. Includes drop and deploy operations for installing fresh test databases compatible with Ed-Fi ODS/API 3.4 and 5.3.
  • buildAndTest: executes the Build, UnitTest, and IntegrationTest commands.
  • package: builds pre-release and release NuGet packages for the Admin App web application.
  • push: uploads a NuGet package to the NuGet feed.
  • buildAndDeployToAdminApiDockerContainer: runs the build operation, update the appsettings.json with provided Docker environment variables and copy over the latest files to existing AdminApi docker container for testing.
  • run: runs the Admin API

Note: use the IsLocalBuild switch to install NuGet.exe if you do not already have it in your local path.

Review the parameters at the top of build.ps1 for additional command line arguments.

Running on Localhost

There are three ways of running Admin API:

  • build.ps1 run to run from the command line.
  • Run inside a container with the help of compose-build-dev.yml.
  • Start from Visual Studio to take advantage of easy debugging integration.

There are several launch profiles available either with build.ps1 or when running from Visual Studio. Review launchSettings for more information. Note that you should use the "Prod" launch setting when running the Postman-based E2E tests.

Configuring Admin API to Run with the ODS/API

Some features of the Admin API require interaction with the ODS/API. For that reason, you may need to launch an instance of the ODS/API. The compose-build-dev.yml file handles this for you.

With the other two options, you will need to startup the ODS/API on your own, using Visual Studio or the command line. Do not start the ODS/API in a separate Docker network from Admin API, because at present both need to access the same EdFi_Admin and EdFi_Security databases. If starting up manually, make sure that both Admin API and ODS/API have the same deployment setting:

  • sharedinstance
  • yearspecific
  • districtspecific

In Admin API, you set this value in the appsettings.json file under AppSettings.ApiStartupType. In the ODS/API, you set it as the ApiSettings.Mode in the appsettings.json (ODS/API 5.x and 6.x) or in web.config (ODS/API 3.x). Please see ODS/API documentation for more information about the differences between these startup modes.

Admin API has a small set of database tables for internal management, which need to be installed into the EdFi_Admin database. The SQL scripts for this are under the Artifacts directory. They can be installed from PowerShell with the following command:

# From AdminApi clone directory
cd eng

# Accepting the default options: MSSQL, on localhost, using integrated security, using EdFi_Admin
./run-dbup-migrations.ps1

# Alternately, override all available settings
$config = @{
    "engine" = "PostgreSQL"
    "databaseServer" = "alternate-hostname"
    "databasePort" = "5466"
    "databaseUser" = "postgres"
    "databasePassword" = "a-strong-password"
    "useIntegratedSecurity" = $false
    "adminDatabaseName" = "EdFi_Admin_543"
}
./run-dbup-migrations.ps1 $config

Resetting the Database State

If you need to reset your databases to a clean slate, run appropriate PowerShell commands in the Ed-Fi-ODS-Implementation repository.

pushd ../Ed-Fi-ODS-Implementation

# Checkout the ODS/API version you need to test with, for example v6.1, v5.3, v5.2, v5.1.1
git checkout v6.1

# Load PowerShell functions
./Initialize-PowershellForDevelopment.ps1

# Wipe out and re-install both databases
Reset-AdminDatabase
Reset-SecurityDatabase

# Wipe out and re-install the databases used by the DB integration tests
Reset-TestAdminDatabase
Reset-TestSecurityDatabase

# Re-run the Admin API migration scripts
popd

eng/run-dbup-migrations.ps1

Running Locally in Docker

As mentioned above, you can run locally in Docker. See docker.md for more information.

Using Keycloak (IDP)

To use Keycloak for authenticating the API, you need to configure the parameters in the OIDC section. Additionally, you must specify with "UseSelfcontainedAuthorization": false, that the API’s own authentication will be disabled in favor of using Keycloak.

Furthermore, when using Keycloak, the Register and Token endpoints will not be available in Swagger or for direct calls. Attempting to access these endpoints will result in a 404 error.

{
  "Authentication": {
    "IssuerUrl": "",
    "SigningKey": "",
    "AllowRegistration": false,
    "OIDC": {
      "Authority": "https://localhost/auth/realms/edfi-admin-console",
      "ValidateIssuer": true,
      "RequireHttpsMetadata": false,
      "EnableServerCertificateCustomValidationCallback": true
    }
  }
}

Running Unit Tests, Integration Tests, and Generating Code Coverage Reports

The source code includes two main types of test projects:

  • Unit tests (*.UnitTests):

    • Run with: build.ps1 -Command UnitTest
    • To collect code coverage, use: build.ps1 -Command UnitTest -RunCoverageAnalysis
      This will generate an HTML report in the coveragereport directory.

  • Integration tests (*.DBTests):
    These tests exercise the repository layer and require a database connection.

    • Run with: build.ps1 -Command IntegrationTest
    • To collect code coverage, use: build.ps1 -Command IntegrationTest -RunCoverageAnalysis
      This will also generate an HTML report in the coveragereport directory.

Alternatively, you can run both unit and integration tests together with:
build.ps1 -Command BuildAndTest [-RunCoverageAnalysis]

Note

Code coverage analysis requires the reportgenerator tool.
Install it with: dotnet tool install -g dotnet-reportgenerator-globaltool

Additionally, there is a set of end-to-end (E2E) tests in Postman.
See E2E Tests/README.md for more information.

All three test suites should pass successfully before merging new code into the main branch.

Application Architecture

The Admin API source code uses ASP.NET but it does not follow the traditional ASP.NET model-view-controller (MVC) approach. Instead it relies on defining Features and then automating the API routing to those features. Conceptually, each Feature is a Controller, though it does not inherit from the .NET Controller class.

Each Feature implements the IFeature interface, which has a single function. That function enables the feature to define its own HTTP endpoint route. The Feature then has Handle function the contains the normal controller logic. Its arguments are automatically interpreted and handled by the ASP.NET Core dependency injection framework.

Database Layer

Database interaction is mediated through Entity Framework Core with two interfaces: IUsersContext handles the EdFi_Admin database and ISecurityContext handles the EdFi_Security database. The name "IUsersContext" derives from the admin database being used to hold Admin App users and now Admin API client credentials.

Validation

Validation of API requests is configured via FluentValidation.

DbInstance Provisioning Jobs

The POST /v2/dbinstances flow is asynchronous. The endpoint persists a Pending DbInstance, schedules CreateInstanceJob, and returns 202 Accepted immediately. A separate recurring CreatePendingDbInstancesDispatcherJob handles sweep-based recovery and capped retries for records that remain in Pending or move to Error.

Use design/DBINSTANCE-PROVISIONING-JOBS.md as the durable design reference for job identities, retry strategy, reconciliation behavior, and Mermaid diagrams of the API and background-job flows.

Feature-specific prerequisites and configuration:

  • AppSettings:adminApiMode must be v2 so startup scheduling registers the recurring dispatcher.
  • Admin API DB migrations must be applied because the flow relies on adminapi.DbInstances and adminapi.JobStatuses.
  • AppSettings:EncryptionKey must be a valid base64-encoded key.
  • ConnectionStrings:EdFi_Ods supplies the connection-string shape used to generate encrypted OdsInstance.ConnectionString values.
  • For PostgreSQL, ConnectionStrings:EdFi_Master should point at the maintenance database postgres, not an ODS database.
  • AppSettings:CreateDbInstancesSweepIntervalInMins controls dispatcher cadence.
  • AppSettings:CreateDbInstancesMaxRetryAttempts controls retry capping.
  • When AppSettings:MultiTenancy is enabled, the active tenant must have tenant-specific connection strings available before the worker runs.