| 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. 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.
| 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) |
...
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.
...