| Table of Contents |
|---|
...
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.
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. All endpoints will include a version prefix.
| API Endpoint | Supported Operations | Function | Request Payload | Response Content |
|---|---|---|---|---|
| /admin/identity/connect/token | POST | Login to retrieve a token for authorized Admin API usage. | { "client_id": "string", "client_secret": "string", "grant_type": "client_credentials", "scope": "string" } | POST: 201 (Created) { "access_token": "string", "expires_in": 3600, "token_type": "Bearer", "scope": "string" } 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) |
Multi-Instance Routes
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:
| API Endpoint | Supported Operations | Function | Request Payload | Response Content |
|---|---|---|---|---|
| /admin/instances | GET | List registered instances | N/A | |
| POST | Register a new instance | |||
| /admin/instances/{id} | GET | Details of an individual instance | N/A | |
| PUT | Update info for an existing instance | |||
| DELETE | Remove an existing instance | N/A | DELETE: 200 (OK), 404 (Not Found) |
Response Structure
API responses are "wrapped" in a common format to ease client interpretation and ingestion.
| Code Block |
|---|
Common Responses
The following API responses are common between endpoints and will utilize a standard response structure around the content that varies.
...
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
...
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
The Admin API will be released as Apache 2.0 source code, as with Ed-Fi's ODS/API Platform and Admin App.
...