Admin API Design
- Jason Hoekstra
- saagar.minocha
- Former user (Deleted)
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 important functions. Automated deployments are becoming more of a trend throughout Ed-Fi technology stack deployments, which can allow for faster and more consistent deployments. An Admin API would enable implementers to automate functions that require manual efforts today, which are known to be blockers to adoption at-scale.
Ed-Fi has provided the Admin App, which is an application that provides a user-interface (UI) to Ed-Fi management functions. 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 .
Below is a table of contents for topics into the Admin API design:
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. The Admin API may be driven by automation scripts, such as PowerShe
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 always 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. The Admin API should use standard OAuth2 authentication flows, as common with many API-based services such as this.
API Endpoints
Below are suggested API endpoints to implement the primary use cases as mentioned above. All endpoints will include a version prefix.
Single and Multi-Instance Routes
Some resources outlined below are scoped to a specific ODS instance, which is inferred from the {instance-id} in the route (e.g. /admin/instances/{instance-id}/applications/{id}). These are valid for single-instance mode installations, using the ID of that single instance. In almost all cases the ID will be 1 , however the instance ID can be retrieved from the GET /admin/instances/ endpoint to verify. "Global" settings such as vendors/ and claimsets/ remain unchanged. In addition, endpoints will be available to register and update ODS/API instances.
| API Endpoint | Supported Operations | Function | Request Payload | Response Content |
|---|---|---|---|---|
| /connect/token | POST | Log in to retrieve a token for authorized Admin API usage | form-urlencoded, not JSON) { | 200 (OK) { "access_token": "string", "expires_in": 0, "token_type": "Bearer", } |
| /connect/register | POST | Create a new identity for Admin API usage. This endpoint can be disabled by system configuration | (form-urlencoded, not JSON) { "ClientId": "string", "ClientSecret": "string", "DisplayName": "string" } | 200 (OK) This endpoint does not return the created application info. |
| /admin/vendors | GET | Retrieve listing of existing vendors | N/A | 200 (OK) |
| POST | Add a new vendor. | { "company": "string", "namespacePrefixes": "string", "contactName": "string", "contactEmailAddress": "string" } | 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 | 200 (OK) |
| PUT | Update vendor information | { "company": "string", "namespacePrefixes": "string", "contactName": "string", "contactEmailAddress": "string" } | 200 (OK) 404 (Not Found) | |
| DELETE | Delete a vendor | N/A | 200 (OK), 404 (Not Found) | |
| /admin/claimsets | GET | Returns list of valid claimsets available in the system (needed for defining applications) | N/A | 200 (OK) |
| /admin/instances | GET | List registered instances | N/A | 200 (OK), 404 (Not Found) |
| POST | Register a new instance | 201 (Created) | ||
| /admin/instances/{id} | GET | Details of an individual instance | N/A | 200 (OK), 404 (Not Found) |
| PUT | Update info for an existing instance | 200 (OK), 404 (Not Found) | ||
| DELETE | Remove an existing instance | N/A | 200 (OK), 404 (Not Found) | |
| /admin/instances/{id}/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/instances/{id}/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/instances/{id}/applications/{id}/reset-credential | PUT | Reset application credential | N/A | 200 OK (Application ID, Key, Secret, API Url) |
Response Structure
( To be determined as part of active design discussions )
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 | 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
Authentication
Clients will authenticate against the Admin API using a registered key and secret to obtain a JSON Web bearer Token (JWT) that must be included on subsequent requests. Token lifetime will be configurable. New clients can register for a key and secret to be issued using a static, configured API key.
The MVP solution will include a built-in Open ID Connect provider implemented using OpenIddict, with plans to allow clients to utilize their own Open ID Connect providers in the future.
Authorization
The endpoints planned for MVP do not require distinct roles or permissions, any authenticated request will have access to all endpoints.
Logging
Hosting and Deployment
Admin API will primarily target Docker hosting solutions, including a Docker image and guidance for introducing the API in the broader ODS Docker ecosystem. As mentioned above, the Admin API is a wholly separate solution from the Admin App, including hosting requirements and release schedule, but implementers may wish to host the Admin App and Admin API side-by-side against the same Database(s) until feature parity is achieved.
Like other Docker images in the ODS solution, the Admin API will utilize a pre-built application package. Implementers who wish to host the Admin API on IIS will be able to do so, using this package, which will be available in the same manner as other applications. Unlike other applications, however, Admin API will not include an installer during MVP, so implementers will need to set up IIS manually or using their own install scripts. Alternatively, Admin API may be hosted using Docker along side an IIS ODS API solution.
Documentation
Admin API will be documented using a combination of general documentation here in Tech Docs, as well as endpoint-specific automated Swagger API Platform documentation available at runtime, including specific request and response models, expected response codes, and descriptive details.
Source Code and Deployment
The Admin API will be released as Apache 2.0 source code, as with Ed-Fi's ODS/API Platform and Admin App.
Initially, the Admin API may be a standalone application within Admin App. This means, to use the Admin API, you will have to deploy Admin App. It is not required to use Admin App for Admin API functionality.
Deliverables
Below is a listing of deliverable details, such as planned roadmap dates, summary of release functionality and links to releases in TechDocs. Release links will expand with tickets and information as design and development of the project continues.
| Version | Roadmap Date | Summary of Functionality | Release Link |
|---|---|---|---|
| Admin App 1.0 |
|
| https://tracker.ed-fi.org/projects/AA/versions/14714 |
| Admin App 1.1 |
|
| https://tracker.ed-fi.org/projects/AA/versions/14802 |
| Admin App 1.2+ | TBD | TBD based on additional field requirements as identified |
Open Questions
Below are open questions as related to the design of the Admin API from the development team and Ed-Fi community. If you have additional needs, questions or other items not addressed in this document, please comment below add it to the list.
a.) What response data is needed back from the Admin API? Common patterns? Response codes?
b.) Does this cover MSP, State and Collaborative needs for automated management? What else is needed (into new tickets)?