Overview
Implementers of Ed-Fi technology have signaled the need for an administrative API (Admin API) to automate functions such as key/secret management, application management and other key functions. Automated deployments are becoming more of a trend throughout Ed-Fi technology stack deployments. An Admin API would enable implementers to automate functions that require manual efforts today.
Ed-Fi's Admin App is an application that provides a user-interface (UI) to some of these functions and will be a basis for Admin API initial functionality. Admin App provides business logic and a user-interface to necessary functions such as credentials, application, vendor and claim set management. The Admin API will leverage the pre-existing and reviewed business logic created in Admin App as a basis of an initial release, however the Admin API would be expected to grow in functionality as requirements are identified by the Ed-Fi community.
This page proposes a design of an Admin API component.
A related epic in Ed-Fi Tracker is available for this effort via AA-1442 - Getting issue details... STATUS .
Use Cases
The Admin API will be called programmatically within automated deployment environments. A knowledgeable person or team of people with IT administrative functions will be responsible for the configuration, usage and security of the Admin API. The Admin API will automate functions currently done today via custom scripting and/or human intervention via a user-interface, such as the Admin App or other management interfaces.
Functional Requirements
Below are functional requirements for an Admin API to automate and manage an Ed-Fi Technology Stack.
Deployment
The Admin API is a standalone component and will not require the Admin App to run. Some early adopters may opt to install both applications side-by-side, as the MVP of Admin API will not be feature-complete when compared to the existing Web UI.
The primary target deployment for Admin API is most requested in Docker-automated environments. Due to the implementation of our Docker images, hosting on IIS will be straightforward using IIS, although will not automated with an installer until after MVP.
Authentication
The Admin API must allow for secure, trusted communication via API. Compared to Admin Web UI, the Admin API will run as a "superuser" capacity as a delegated IT administrator with responsibilities of managing a secure environment. Multiple and role-based consumers may be introduced for future API endpoints, but for initial release, a single set of credentials would be acceptable.
API Endpoints
Below are suggested API endpoints to implement the primary use cases as mentioned above.
NOTE: need to address multi-instance in the API endpoint
| API Endpoint | Supported Operations | Function | Request Payload | Response Content |
|---|---|---|---|---|
| /admin/identity/connect/token | POST | Login to retrieve a token for authorized Admin API usage. | POST: 201 (Created) ALL: 401 (Unauthorized), 500 (System Error) | |
| /admin/identity/api/client | POST | Create a new identity for Admin API usage. | POST: 201 (Created) ALL: 401 (Unauthorized), 500 (System Error) | |
| /admin/vendors | GET | Retrieve listing of existing vendors | N/A | GET: 200 (OK) |
| POST | Add a new vendor. | { "company": "string", "namespacePrefixes": "string", "contactName": "string", "contactEmailAddress": "string" } | POST: 201 (Created) { "vendorId": 0 "company": "string", "namespacePrefixes": "string", "contactName": "string", "contactEmailAddress": "string" } Header: Location attribute: address to retrieve the created object | |
| /admin/vendors/{id} | GET | Retrieve detail information for an existing vendor | N/A | GET: 204 (OK) |
| PUT | Update vendor information | { "company": "string", "namespacePrefixes": "string", "contactName": "string", "contactEmailAddress": "string" } | PUT: 204 (No Content / Updated), 404 (Not Found) | |
| DELETE | Delete a vendor | N/A | DELETE: 200 (OK), 404 (Not Found) | |
| /admin/claimsets | GET | Returns list of valid claimsets available in the system (needed for defining applications) | N/A | GET: 200 (OK) |
| /admin/applications | GET | Retrieve listing of existing applications | N/A | GET: 200 (OK) ALL: 401 (Unauthorized), 500 (System Error) |
| POST | Create a new application. | { "applicationName": "string", "vendorId": 0, "claimSetName": "string", "profileId": 0, "educationOrganizationIds": [0,] } | POST: 201 (Created) { "applicationId": 0, "applicationName": "string", "vendorId": 0, "claimSetName": "string", "profileId": 0, "educationOrganizationIds": [0,] } Header: Location attribute: address to retrieve the created object | |
| /admin/applications/{id} | GET | Retrieve detail information for an existing application. | N/A | GET: 200 (OK) |
| PUT | Update application information. | { "applicationName": "string", "vendorId": 0, "claimSetName": "string", "profileId": 0, "educationOrganizationIds": [0,] } | PUT: 204 (No Content / Updated), 404 (Not Found) | |
| DELETE | Delete an existing application. | N/A | DELETE: 200 (OK), 404 (Not Found) | |
| /admin/applications/{id}/reset-credential | PUT | Reset application credential | N/A | 200 OK (Application ID, Key, Secret, API Url) |
Response Structure
API responses are "wrapped" in a common format to ease client interpretation and ingestion.
Common Responses
The following API responses are common between endpoints and will utilize a standard response structure around the content that varies.
| Response Code | Valid Verbs | Description | Structure |
|---|---|---|---|
| 400 Bad Request | POST, PUT, DELETE | Problem with request body (validation issue or incorrect use) | |
| 401 Unauthorized | All | Bearer token is missing or invalid | |
| 500 Internal Server Error | All | Unexpected error has occurred |
Technical Requirements
Below are technical requirements for the Admin API:
Solution Design
Admin API will be implemented as a new .NET 6 'minimal' API project in the current ODS-Tools solution and repository. While it will share logic with the current Web UI, it will be a separate application.
The ODS-Tools solution currently includes a layer of abstraction around business logic in the form of the EdFi.Ods.AdminApp.Management library. Rather than further abstract the functional logic in Admin App, the API project will utilize this code library, including introducing new API-scoped implementations for model interfaces that may differ from similar functions in the existing Web. The Management library, like the Web UI, currently targets .NET 3.1. In order to safely enable side-by-side implementation, the library (and its installation-specific counterparts) will be changed to target .NET Standard 2.1, which is compatible with both .NET Core 3.1 and .NET 6.
Testing
Absent from the above diagram are automated test projects. The existing app functionality in AdminApp.Management is well-covered by unit and integration tests. Rather than doubling down on those, we will plan on introducing end-to-end tests using Cucumber or PostMan automation to verify the API's response for different scenarios.
Authentication and Authorization
- Hints at authentication/authorization — Data Import TSS copy over would be fine, or updates from that good too
Authorization
Authentication
Logging
Documentation
Hosting and Deployment
- Hints at deployment requirements for Admin API standalone in Docker and Windows configs. (Docker the focus)
Source Code
The Admin API will be released as Apache 2.0 source code, as with Ed-Fi's ODS/API Platform and Admin App.