| Info | ||
|---|---|---|
| ||
This Admin API design document is in draft status and evolving as informed by the Ed-Fi community. Please use the Comments section below for any feedback into the design of Admin API. |
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.
...
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
...
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 | ||
|---|---|---|---|---|---|---|
| /identityconnect/oauth/token | POST | Login Log in to retrieve a token for authorized Admin API usage. | form-urlencoded, not JSON) { "scope": "string"
| POST: 201 (Created200 (OK) { "access_token": "string", "expires_in": 36000, "token_type": "Bearer", "scope": "string" }ALL: 401 (Unauthorized), 500 (System Error) | ||
| /identity/client/connect/register | POST | Create a new identity for Admin API usage. | POST: 201 (Created) ALL: 401 (Unauthorized), 500 (System Error) | 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 | GET: 200 (OK)ALL: 401 (Unauthorized), 500 (System Error) | ||
| 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 200 (OK) | ||
| PUT | Update vendor information | { "company": "string", "namespacePrefixes": "string", "contactName": "string", "contactEmailAddress": "string" } | PUT: 204 (No Content / Updated), 200 (OK) 404 (Not Found) | |||
| DELETE | Delete a vendor | N/A | DELETE: 200 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/AGET: 200 (OK | 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) |
...
When administrating a District- or Year- Specific multi-instance ODS, each instance-specific route will be prefixed by instance ID. For example. /admin/applications/{id} becomes /admin/instances/{instance-id}/applications/{id} . "Global" settings such as vendors/ and claimsets/ remain unchanged. In addition, endpoints will be available to register and update ODS/API instances:
...
...
Response Structure
( To be determined as part of active design discussions )
...
| 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 |
...
The Admin API will be released as Apache 2.0 source code, as with Ed-Fi's ODS/API Platform and Admin App.
...
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)?