| 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. |
...
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 ID can be retrieved by GETing the /admin/instances/ endpoint to be sure. "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 |
|---|---|---|---|---|
| /identity/oauth/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) |
| /identity/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/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) |
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:
...
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 |
...