Skip to content

Latest commit

 

History

History
251 lines (196 loc) · 10.2 KB

developer.md

File metadata and controls

251 lines (196 loc) · 10.2 KB

Admin API Developer Instructions

Contents

Development Pre-Requisites

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 6.0 SDK or newer is installed. Other dependencies tools are downloaded as needed (nuget, nunit).

Available command (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.

Testing Admin API

In source code there are two test projects:

  • Unit tests that are completely isolated.
  • The DB Tests project is a set of integration tests that exercise the repository layer.

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

All three of these test suites should be 100% green 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.

Bulk Application Creation

This PowerShell script creates multiple vendors and applications upon execution and stores the generated keys/secrets in a file. The script utilizes a CSV file as input to specify the vendors and applications to be created. The script prevents duplicate creation of vendors and applications by skipping existing combinations. Remember to store keys/secrets securely.

Instructions

  1. Download the code: [email protected]:Ed-Fi-Alliance-OSS/AdminAPI-1.x.git

  2. Open a PowerShell window in Administrator mode and navigate to the /eng/bulk-key-creation folder.

  3. Populate the sample CSV with the required vendor and application information.

  4. Run the following PowerShell command to load modules for Applications creation:

         Import-Module .\Bulk-EdFiOdsApplications.psm1

  5. The Bulk Register Applications can take a number of parameters, copy and modify the following parameter code to fit your needs:

    $parameters = @{
    CSVFilePath = "District details.csv"
    BaseApiUrl = "https://localhost/AdminApi"
    NamespacePrefixes = "uri://ed-fi.org/"
    Key = "YourAdminApiUser"
    Secret = "yourAdminApiPassword"
    ClaimsetName = "District Hosted SIS Vendor"
    logRootPath = "Logs"
}

  6. Run the following command in the PowerShell window:

      Bulk-EdFiOdsApplications $parameters

  7. A new file will be create with the Key and Secrets

Parameters definition
  • CSVFilePath The csv file to be processed
  • BaseApiUrl The Admin Api url, Example: https://localhost/AdminApi1x
  • namespacePrefixes The namespace for the vendor, Example: uri://ed-fi.org/
  • Key The Key to authenticate with the API
  • Secret The Secret to authenticate with the API
  • ClaimsetName The claim name that will be assigned to the application, Ex: "District Hosted SIS Vendor"
  • logRootPath The Path where you could find the log file

Logs

By default, the script creates log files, to review them go to the root directory and find the Logs folder.