WI DPI WISEdata Ed-Fi Docs
Development Resources
- Jaidaa Shafaei
- heather.kluck
Ed-Fi Resources
Best Practices
Troubleshooting - Ed-Fi ODS-API Error Responses
WISEdata Ed-Fi Software Development Kits (SDK)
Coming soon: Ed-Fi SDK 7.x For 2025-26 SY
Ed-Fi SDK 6.x (v3 and v4 consolidated) For 2023-24 and 2024-25 SY
Ed-Fi SDK 6.x For 2023-24 SY
Ed-Fi SDK 5.3 For 2022-23 SY
DPI generates an Ed-Fi SDK in C# version only. Use the Ed-Fi instructions for generating an SDK in other programming languages: https://techdocs.ed-fi.org/display/ODSAPIS3V61/Using+Code+Generation+to+Create+an+SDK
WISEdata Ed-Fi REST Programmerโs Guide
PREFACE
CONTEXT
Wisconsin Department of Public Instructionโs (DPI) WISEdata project is about improving Federal reporting. Federal reporting can be improved by replacing individual legacy collection systems (ISES, CWCS, etc) with a cohesive interoperability collection framework. DPI has chosen the Ed-Fi interoperability framework to facilitate collecting local education agency (LEA) information. This framework will need to be implemented (if it is not already) by the LEAโs Student Information System (SIS). The SIS software will push data to DPI via a web service defined by the Ed-Fi framework (see Figure-1).
PURPOSE
The purpose of this document is to describe the process of sending and receiving data using the Ed-Fi REST client against the Ed-Fi API hosted by DPI (WISEdata). The API follows REST guidelines which makes sending and receiving data relatively standard (viaย HTTP verbs like GET and POST). This document also describes the authorization using OAuth 2 which is critical for connecting to the Ed-Fi API.ย
Note: This information is also documented by Ed-Fi and DLP. It is strongly recommended that you review their documentation which is listed in the references sections.
USE OF THIS GUIDE
This document is appropriate for programmers who wish to write clients to send requests to the WISEdata via secure RESTful Ed-Fi API.
The use of this document assumes no particular programming language or framework. However, the programmer should be familiar with RESTful services and Basic HTTP Authentication. A brief overview of these concepts is given below. References for additional reading are also provided
DEFINITIONS, ACRONYMS, AND ABBREVIATIONS
Term | Definition |
CWCS | Course Work Completion - DPI legacy system - Collects relational information about students and courses. |
DLP | Double Line Partner - Ed-Fi partners with DLP as the development shop for their organization. |
DPI | Wisconsin Department of Public Instructionย Learn more: Wisconsin Department of Public Instruction ย |
Ed-Fi | Ed-Fi technology serves as the foundation for enabling interoperability among secure education data systems designed to improve student achievement and teacher satisfaction. Learn more: Homepage | Ed-Fi Alliance ย |
HTTPS | Hypertext Transfer Protocol over SSL (Secure Socket Layer) |
ISES | Individual Student Enrollment System - DPI Legacy System - (subsystems include ISES Third Friday of September, Year End, Child Count, and Discipline) Includes student demographic and outcome data needed to meet the ESEA report card requirements at the state, district, and school levels. The ISES requires that schools and/or districts submit data on students enrolled during the previous school year, students enrolled on the Third Friday of September of the current year, students with disabilities enrolled on October First of the current year, and students removed under disciplinary action. |
OAuth 2 | OAuth 2 provides client applications a secure delegated access' to server resources on behalf of a resource owner. Learn more: http://oauth.net/2/ ย |
REST | Representational State Transfer |
WISEdata | With regards to this document - WISEdata is the DPI implementation of the Ed-Fi interoperability framework to facilitate collecting local education agency (LEA) information. WISEdata has other focuses such as student privacy and security. |
REFERENCES
Subjectย | URL/Document |
DLP - Documentation | |
Ed-Fi Tech Docs | |
Ed-Fi REST API Guidelines | http://www.ed-fi.org/assets/2014/06/Public-REST-API-Design-Guidelines-Revision-2-1st-Draft.pdfย |
SYSTEM OVERVIEW
The Ed-Fi API exposes endpoints for submitting and retrieving educational data. Those calls are secure and synchronous (the response is immediately returned).ย ย
PREREQUISITESย
CREDENTIALS
The Ed-Fi API is service secured via OAuth 2.
An OAuth key and secret (per district) is needed to make REST calls.
Secretย
Get from DPI - it will be in the Getting Started Guide
Key
Get from DPI - it will be in the Getting Started Guide
Each OAuth credential needs to be associated with the correct district which will be done by DPI.
Test district ID
Get from DPI - it will be in the Getting Started Guide
Test school
Get from DPI - it will be in the Getting Started Guide
TESTING TOOLS
A REST client which can authenticate via OAuth 2. There are many free and paid REST clients that you can use for testing. The two clients that we use are listed below. Both are free.
SoapUI (version 4.6.4): Besides supporting SOAP requests, it also has a REST client. The World's Most Popular API Testing Tool | SoapUI
RestClient 2: This is a FireFox extension. According to the developer,ย they also have an extension for Safari and for Chrome. Developer website: RESTClient, a debugger for RESTful web services.
A web traffic tracer / debugger. There are a number of web debuggers out there. The REST clients above will (SoapUI or RestClient2) will show web traffic when you make a request. The web debuggers can be handy when creating request via the DPI provided WISEdata Ed-Fi REST SDK or a proprietary Ed-Fi REST client.ย
Fiddler is free and one of the more popular web debuggers Web Debugging Proxy and Troubleshooting Tools | Fiddler
Wireshark Wireshark ยท Go Deep
WISEdata Ed-Fi REST SDK.zip which is.ย
The SDK was Written in C# / .NET and developed using Visual Studio 2013.
The SDK has code for OAuth 2, Ed-Fi REST clients, and integration/unit tests.
There is more information about the SDK in the Appendix - WISEdata Ed-Fi REST SDKย
The Ed-Fi REST clients can be created manually for C# or Java using the DLP generator (see Appendix - Manually Creating the Ed-Fi REST client).
It is not mandatory to use the DLP provided client. However, when developing an Ed-Fi REST client adhere to the Design Guidelines.
AUTHENTICATION - OAUTH 2
PREREQUISITESย
A REST client is required to make REST calls to the Ed-Fi API.
The client that will publish data to the Ed-Fi API should be the SIS vendor software. The SIS implementation will likely be based on the Ed-Fi REST client (an example of the client code is listed below in Appendix).
The client which is being used in the testing phase is called Swagger UI
A client key and secret is required to connect
DPI will provide the key and secret for each LEA/District to SIS vendors.
These are credentials to authenticate/authorize a client.
See Figure 2 for an example. Note the key/secret pair are entered first. Next, the user has to press the โGet Tokenโ button to get a token which is required to make REST calls.
Authorization via OAuth 2
DEFINITIONS
OAuth 2
This is a protocol that provides clients access to server resources without including client credentials. For more information see: OAuth ย
For more information about Ed-Fi OAuth 2 authentication see http://www.ed-fi.org/assets/2013/11/Public-Ed-Fi-REST-API-Design-Guidelines-1.2.pdf
API URL
The URL to the Ed-Fi API RESTful web service
ex. https://edfi-rest.dpi.wi.gov/ (not a working URL)
Admin URL
The URL to the Ed-Fi OAuth web service
Key
Part of the clients credentials
DPI will provide each LEA a Key
ex. ekVNpbjj6SbQ
Secret
Part of the clients credentials
DPI will provide each LEA a secret
ex. 9mnMlZKaswgW9RizPdEKdk
Token
A value obtained in the OAuth protocol which is used to access the API Server
Ed-Fi Two-Legged OAuth 2 Protocol Sequence:
POST https://uaapps.dpi.wi.gov/EdFiWebApi/oauth/authorizeย ย
Include the paremeter โClient_idโ with the clients Key value
include the paremeter โRequest_typeโ as โcodeโ
Store the response as client access code
POST https://uaapps.dpi.wi.gov/EdFiWebApi/oauth/tokenย
include the parameter โClient_idโ with the clients Key value
include the parameter โClient_secretโ with the clients secret value
include the parameter โCodeโ with the clients access code value
include the parameter โGrant_typeโ with the value โauthorization_codeโ
Store the response as the client access token
Make REST API calls to https://uaapps.dpi.wi.gov/EdFiWebApi/api/v2.0ย
Include a header โAuthorizationโ with the value โBearerโ + Token
SERVICES
All of the endpoints, sample data, and schema information can be found and tested via Swagger UI located here: https://uaapps.dpi.wi.gov/EdFiSwagger/
PROFILES:
The following is a document which describes profiles in the Ed-Fi API: https://techdocs.ed-fi.org/display/ODSAPI20/API+Profiles
Wisconsin DPIโs main purpose with profiles is to limit the amount of data that a SIS vendor can send via the API. Wisconsin DPI only wants to collect certain elements as noted above.ย
The default API Section dropdown value is Resources. A SIS can see the resources as restricted by the profile change the dropdown.
The API requires a content type be sent with a any HTTP action (ex. GET, POST). The content type is standardized, but lengthy. Public school clients trying to GET a student have to send the content type โapplication/vnd.ed-fi.student.widpi-profile-public.readable+jsonโ which is highlighted in the image below. If the same SIS wants to POST a student school association they have to send the content type โapplication/vnd.ed-fi.studentschoolassociation.widpi-profile-public.writable+jsonโ.
Note: the SIS still send the JSON to the same endpoints regardless of profiles.
CLAIMSETS:
The following document has more detail on claimsets: https://techdocs.ed-fi.org/display/ODSAPI20/Security+Configuration+Data+Stores
Wisconsin DPI restrict resources in the Ed-Fi API by linking a SIS key to a claimset. The claimset is linked to resources that a vendor can access and how they access the resource (authorization strategy). SIS vendors donโt need to know a lot about claimsets. If you GET/POST a resources outside the Wisconsin DPI domain you might get a error about a claimset. Wisconsin DPI can help confirm if the issue.
SAMPLES
All of the endpoints, sample data, and schema information can be found and tested via Swagger UI located here: https://uaapps.dpi.wi.gov/EdFiSwagger/
Note that samples may not contain all data required or conditionally required by Wisconsin DPI, but the samples should help you get started.ย You may find JSON samples in the Data Domains & Endpoints area under each endpoint.
A couple of key notes:
studentUniqueId is the same as WISEid.ย In production, Choice schools / districts will have to use the separate WI DPI WISEid system to obtain WISEids and upload or manual input to the SIS.ย To get a set of WISEids for testing in the UAT โsandboxโ, submit a request and a list of WISEids for testing will be provided.
SchoolId is created from the test Agency ID we create for your test school / district in the UAT โsandboxโ environment.ย This is only to the UAT โsandboxโ environment. You will need to go to the WISEdata Ed-Fi Credential system to get the Agency ID (this is the same system you use to get your credentials (key and secret)) that can then be used to derive the schoolId (read this blog post). To get LEA and school ids for the production environment, take a look at this blog post for more information.
Retrieving students that you have already sent via a POST requires that you have sent a POST for the /studentSchoolAssociation related to that student.ย You can only update and retrieve students in a school/district that relate to your credentials..
educationalOrganizationId in /studentAcademicRecord is the SchoolId.ย It appears Ed-Fi kept this generic to allow for a district level or some other level of academic record other than school level.
https://wisconsindpi.atlassian.net/wiki/spaces/widpiedfi/pages/2294032/Data+Domains+Endpoints
SCHEMAS
All of the endpoints, sample data, and schema information can be found and tested via Swagger UI located here: https://uaapps.dpi.wi.gov/EdFiSwagger/
HTTP RESPONSES
RESPONSE CODES
A core tenet of RESTful APIs is embracing HTTP response codes toย communicate status information. An API consumer should be able to inspect theย HTTP response code and understand the status of its request. The followingย response codes are used when responding to requests.ย
HTTP Response Code | Name | Reason(s) |
200 | OK | Returned after a successful GET, PUT, or DELETE. A PUT or DELETE response will not contain a body.ย |
201 | Created | Returned after a successful POST. The response from a POST will also include a Location in the Header pointing to the newly added resource. A POST response will not contain a body.ย |
202 | Accepted | Returned for a request that has been accepted for processing, but the processing has not yet been completed.ย |
204 | No Contentย | Returned when the server has fulfilled the request but does not return an entity body.ย |
304 | Not Modifiedย | Returned when the client includes theย โIf-None-Matchโ header containing theย requested resourceโs last known ETag.ย |
400 | Bad Requestย | Returned if the query string for a GET or the body for a POST or PUT is malformed or missing required fields. The body of the response will contain a descriptive error message.ย |
401 | Unauthorized | Returned if the access token is invalid. The response will not contain a body.ย |
403 | Forbidden | Returned if the user to which the access token is tied does not have permissions to the requested resource. The body of the response will contain a descriptive error message. |
404 | Not Foundย | Returned if a resource is not found. The response will not contain a body.ย |
412 | Precondition Failedย | Returned if an if-Match header precondition fails. |
500 | Internal Server Errorย | Returned if the server encountered an unexpected error during the operation.The response will not contain a body. |
ERRORS
If an error occurs on the server, a 500 (Internal Server Error) code will beย
returned along with the addition of a โresponseStatusโ property in the responseย
body, containing the error details. For example:ย
{ย
ย "responseStatus": {ย
ย "errorCode": "DataAccessException",ย
ย "message": "Unable to communicate with database",ย
ย "stackTrace": "โฆ",ย
ย "errors": []ย
ย }ย
}ย
WISEDATA ED-FI REST SDK
REQUIREMENTS
Manually creating the Ed-Fi REST client: All of the steps to create the REST client can be found in the โreadmeโ in the ED-FI REST SDK Repository: https://github.com/DoubleLinePartners/Ed-Fi-REST-SDK
The following is an outline of the steps need to manually create the client.
1. MACHINE SETUP
Download the Java SDK
Download SBT and install. Just under the "Installing sbt" header download the appropriate package for your operating system.ย ย
Ensure your environment can find javac. If you're on Windows set the PATH environment variable to find the jdk bin directory (e.g. C:\Program Files\Java\jdk1.7.0_51\bin).
Download the ED-FI REST SDK Repository (look at the readme and its instructions) from the Double Line Partners GitHubย
2. GENERATING THE REST CLIENT
The rest of the instructions can be found in the โreadmeโ in the DLP ED-FI REST SDKย ย
Open a command prompt to the ed-fi-rest-sdk folder and type "sbt assembly". This will build the Swagger codegen jar file.
Navigate to the folder where the jar file was created and run the command from the command prompt for each section in Swagger. This location is listed close to the end of the information log that is output during sbt generation.
Generate C# source files by running the generator once for each for each API section: descriptors, resources, and types.
java -jar sdk-generate.jar csharp --url https://{Domain root of API}/metadata/{section}/api-docs --baseDir {destination folder} --apiPackage {API namespace} --helperPackage {SDK namespace} --modelPackage {Model namespace}
Create a new class library in Visual Studio and include all of the generated files.
Use the Package Manager Console to install the RestSharp library (Install-Package Restsharp)
ย
Swagger
WISEdata API 6.x Used for 23/24 and 24/25 SY
WISEdata API 5.x Used for 22/23 SY
ย
ย
Wisconsin Department of Public Instruction