Introduction to the Admin API
- Ecleamus Ricks
Introduction
This knowledge base article attempts to provide a detailed overview for the Ed-Fi Admin Application Programming Interface, commonly referred to as Admin API.
This article assumes prerequisite knowledge from:
If you have not already completed these courses, we recommend doing so before attempting to digest the information presented in this article.
Overview of Admin API
Admin API is an administrative application that manages Ed-Fi ODS/API admin and security (e.g. ClaimSets) metadata. It has a programmatic interface, aligned with the Ed-Fi API, so it is meant for scripting, dev-ops or integration with portals and other administrative interfaces.
What to Use Admin API For
Admin API is used to administrate essential data for the Ed-Fi ODS/API. It can manage applications, claim sets, ODS instance metadata, profiles, vendors and other system-level data to enable Ed-FI ODS/API operation.
When to Use (and Not Use) Admin API
Admin API is targeted for use by state agencies, collaboratives and managed service providers of multi-instance implementations.
This product should not be confused with its predecessor, Admin App. Admin App was mostly targeted for use at the district-level operations for individual districts or implementations. It offered a user interface designed for IT administrators at schools and/or districts.
How to Use Admin API
Deployment
You can find detailed instructions for installation here: Admin API Installation.
Registration
After completing installation, complete the first-time configuration steps outlined here: First Time Configuration for Admin API 2.x
Example Use Cases
Admin API does not have a user interface therefore Postman, Swagger, scripts or other administrative applications must be used to leverage it. The following examples will include example Python scripts to demonstrate common tasks.
Ed-Fi ODS Instances Management
We’ll start with creating an Ed-Fi ODS instance since an instance is required for application creation. Instances can be created with "v2/odsInstances" POST endpoint.
Vendor Administration
While vendor information is not ODS instance specific, the vendor is required for application creation too. Vendors can be created with "v2/vendors" POST endpoint.
Application Administration
With an ODS instance id and vendor id, an application can now be created with "v2/applications" POST endpoint.
Claim Set Administration
Custom claim sets can be created and managed using "ClaimSets" endpoints.
Common Response Codes
The following API responses are common between endpoints.
Response Code | Description | Valid for Verbs | Notes |
200 SUCCESS | Request was successful | ALL |
|
201 CREATED | Resource was created successfully | POST | Response will also include a location header which directs to the new resource |
400 BAD REQUEST | Invalid request payload - See errors for details | POST, PUT |
|
401 UNAUTHORIZED | Missing or invalid authentication token | ALL |
|
403 FORBIDDEN | Authentication token is valid, but resource is outside of authenticated scope | ALL |
|
404 NOT FOUND | Resource with given id not found | ALL |
|
500 INTERNAL SERVER ERROR | Unexpected error on the system - See error for details | ALL |
|
Useful Links
Here are a few other useful links to continue your learning: