The Ed-Fi ODS / API allows platform hosts to configure API Profiles to control access to specific resources. Profile configuration supports flexible, fine-grained control – but this level of control can get complicated quickly, making it difficult to understand exactly how the configuration will be applied in practice. This article provides guidance for generating and using the Ed-Fi ODS / API Client Java SDK with Profiles support, which gives platform implementers a means of verifying that the platform configuration is providing the desired access control.
The high-level steps are:
Each step is outlined in detail, below.
If you've created one of the auto-generated Client SDKs using the instructions in the API Client Developers' Guide, you'll have already done steps 1 through 3.
Step 1. Install and Configure Required Software
This step ensures you have the prerequisite software on your development machine.
- Install the Java SDK. Version 8 or newer is required.
- Install the Scala Build Tool (sbt).
- Set the Windows PATH environment variable to find the jdk bin directory.
Step 2. Download the Ed-Fi ODS Client SDK Source Code
Follow these steps to download the repository archive and extract it:
- Navigate to GitHub and select the appropriate version of the source code:
- Latest Stable Release (v2.3): https://github.com/Ed-Fi-Alliance/Ed-Fi-ODS-API-SDK/tree/v2.3
- Latest Daily Source: https://github.com/Ed-Fi-Alliance/Ed-Fi-ODS-API-SDK/tree/development
- Download the repository archive to your local drive.
- In Windows Explorer, right-click on the downloaded ZIP files and select “Properties.” On the General tab, press the Unblock button to allow the contents of the contained scripts to execute properly.
- In Windows Explorer, right-click on the downloaded ZIP file and select Extract All… Enter “C:\” for the target folder. The ZIP files contain an embedded folder ending in “-2.0” (i.e., C:\Ed-Fi-ODS-API-SDK-2.3).
- After the extractions are complete, rename the folder to remove the “-2.3” from the folder name (i.e., C:\Ed-Fi-ODS-API-SDK).
Step 3. Build the Swagger codegen jar File
- Open a command prompt to C:\Ed-Fi-ODS-API-SDK and type "sbt assembly". This will build the Swagger codegen jar file in C:\Ed-Fi-ODS-API-SDK\target\scala-2.10 using the Scala Build Tool installed above.
Step 4. Generate the Java SDK
This step will generate the source code files with the logic necessary to call a particular Ed-Fi ODS API.
- Open the the Ed-Fi ODS / API solution in Visual Studio, and start the solution using the "Start Without Debugging" option (generally available as Ctrl+F5 with the keyboard).
With the Swagger metadata endpoint available, run the following commands from a command window:
Step 5. Create the Sample Java Project
The steps for generating the Java Profiles SDK closely follow those detailed on the Developers' Guide, with some differences.
- Create a new Maven project in Eclipse.
- Check the box to Create a simple project.
- Enter “generated-java-sdk” for the Group Id and Artifact Id and click Finish.
Expand the project and double-click the pom.xml file. Select the pom.xml tab to view the source. Locate the example.pom.xml file from the generated docs (C:\Ed-Fi-ODS-API-SDK\JavaSDK ) and copy the contents of the file. Paste the contents of the file into the pom.xml tab. Then, remove the context on line 7 (shown below) and save the file.
Your pom.xml file should now look like the following:
Create the following packages under src/main/java:
- Import (File > Import > General > File System) the classes from the generated documentation (C:\Ed-Fi-ODS-API-SDK\JavaSDK\src\EdFi\OdsApis\) into the package with the same name. Be sure to select all of the classes in each package to be imported by choosing Select All in the dialog.
See the image below showing an example of loading the the Apis classes into the Apis package:
After importing all the required classes, your project should resemble the following:
- Update the Maven Project. Right-click the project and select Maven > Update Project. You can disregard the configuration warning.
- Open the RestApiTokenRetriever class. Navigate to the bottom of the class and locate the two inner classes: AccessCodeResponse and BearerTokenResponse. Generate getters and setters for the seven fields in these two classes. Save the file. (There is currently a bug, and this is the fix).
Add a class to the src/main/java folder (New > Class). Name the class “test” and add the stub for the main method - check the box for
public static void main(String args).
Paste the following into the
Add the following references to the top of the test.java file. Save the file.
Step 6. Modify the Authorization Metadata for Verification Purposes
One manual change will be made to the EdFi_Security database for verification purposes. This change provides the out-of-the-box sandbox API key/secret permissions to modify School information.
Using SQL Server Management Studio, execute the following commands against the EdFi_Security database:
Step 7. Run the Test Class
Select the test.java class and run it as a Java application. The resulting output will contain the response code and result of the following operations:
- Get all
- No labels