This version of the Ed-Fi ODS / API is no longer supported. See the Ed-Fi Technology Version Index for a link to the latest version.

 

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

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.

Step 2. Download the Ed-Fi ODS Client SDK Source Code

The Ed-Fi ODS / API Client SDK source code is contained in an Ed-Fi repository called Ed-Fi-ODS-API-SDK (https://github.com/Ed-Fi-Alliance/Ed-Fi-ODS-API-SDK). Follow these steps to download the repository archive and extract it:

  • Navigate to https://github.com/Ed-Fi-Alliance/Ed-Fi-ODS-API-SDK and 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 Unblock 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 “-master” (i.e., C:\Ed-Fi-ODS-API-SDK-master). 
  • After the extractions are complete, rename the folder to remove the “-master” 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.

  1. 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).
  2. With the Swagger metadata endpoint available, run the following commands from a command window:
  • java -jar C:\Ed-Fi-ODS-API-SDK\Ed-Fi-ODS-API-SDK\target\scala-2.10\sdk-generate.jar java --url http://localhost:54746/metadata/Test-Profile-Resource-Includeonly/api-docs/ --baseDir C:\Ed-Fi-ODS-API-SDK\Ed-Fi-ODS-API-SDK\JavaSDK --apiPackage EdFi.OdsApi.Apis.Test_Profile_Resource_Includeonly --helperPackage EdFi.OdsApi.Sdk --modelPackage EdFi.OdsApi.Models.Test_Profile_Resource_Includeonly
  • java -jar C:\Ed-Fi-ODS-API-SDK\Ed-Fi-ODS-API-SDK\target\scala-2.10\sdk-generate.jar java --url http://localhost:54746/metadata/Test-Profile-Resource-Excludeonly/api-docs/ --baseDir C:\Ed-Fi-ODS-API-SDK\Ed-Fi-ODS-API-SDK\JavaSDK --apiPackage EdFi.OdsApi.Apis.Test_Profile_Resource_Excludeonly --helperPackage EdFi.OdsApi.Sdk --modelPackage EdFi.OdsApi.Models.Test_Profile_Resource_Excludeonly

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.

  1. Create a new Maven project in Eclipse.


  2. Check the box to Create a simple project.


  3. Enter “generated-java-sdk” for the Group Id and Artifact Id and click Finish.


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

    <sourceDirectory>src</sourceDirectory>

    Your pom.xml file should now look like the following:



  5. Create the following packages under src/main/java:

    • EdFi.OdsApi.Apis

    • EdFi.OdsApi.Models

    • EdFi.OdsApi.Sdk

  6. 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:


     
  7. Update the Maven Project. Right-click the project and select Maven > Update Project. You can disregard the configuration warning.

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

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

  10. Paste the following into the main method: 

    // Trust all SSL certs – needed unless signed SSL certificates are configured.
CertificateValidationDisabler.disable(); // generated helper class
 
// Oauth configuration
String oauthUrl = "http://localhost:54746/";
String clientKey = "5iqu6lX4JJAS";
String clientSecret = "EytEoZqr2a0n3jMD5qsyUyiB";

 
// TokenRetriever makes the oauth calls
TokenRetriever tokenRetriever = new RestApiTokenRetriever(oauthUrl, clientKey, clientSecret);

 
// JAX-RS dependency, installed via Maven
ClientBuilder clientBuilder = ClientBuilder.newBuilder();
Client client = clientBuilder.build().register(new BearerTokenAuthenticator(tokenRetriever));
WebTarget target = client.target("http://localhost:54746/api/v2.0/2015");

// GET schools
EdFi.OdsApi.Apis.Test_Profile_Resource_Includeonly.SchoolsApi includedSchoolApi = new EdFi.OdsApi.Apis.Test_Profile_Resource_Includeonly.SchoolsApi(target);

 
// RestResponse wraps a JAX-RS Response to provide a properly typed readEntity() method
RestResponse<List<EdFi.OdsApi.Models.Test_Profile_Resource_Includeonly.School_Readable>> preModificationsResponse = includedSchoolApi.getSchoolsAll(null, null); // offset, limit

 
System.out.println("Response code of profile include readable SchoolApi.GetAll() is " + preModificationsResponse.getStatus()); 
System.out.println("Results of profile include readable GetAll() before modifications: ");

 
for (EdFi.OdsApi.Models.Test_Profile_Resource_Includeonly.School_Readable school : preModificationsResponse.readEntity())
{ 
    System.out.println("Name - " + school.getNameOfInstitution() + " Id - " + school.getId()); 
}
 
System.out.println("");

 
String schoolOriginalName = preModificationsResponse.readEntity().get(0).getNameOfInstitution();
String schoolEntityIdToModify = preModificationsResponse.readEntity().get(0).getId();
Integer schoolIdToModify = preModificationsResponse.readEntity().get(0).getSchoolId();

// Create a profile exclude writable school
EdFi.OdsApi.Models.Test_Profile_Resource_Excludeonly.School_Writable modifiedWritableSchool = new EdFi.OdsApi.Models.Test_Profile_Resource_Excludeonly.School_Writable();
modifiedWritableSchool.setId(schoolEntityIdToModify);
modifiedWritableSchool.setNameOfInstitution("The School of Data Modification");
modifiedWritableSchool.setStateOrganizationId("XYZ");
modifiedWritableSchool.setSchoolId(schoolIdToModify);

// Put the modified school resource
EdFi.OdsApi.Apis.Test_Profile_Resource_Excludeonly.SchoolsApi excludedSchoolApi = new EdFi.OdsApi.Apis.Test_Profile_Resource_Excludeonly.SchoolsApi(target);
Response putResponse = excludedSchoolApi.putSchool(schoolEntityIdToModify, "", modifiedWritableSchool);

// Create a new profile exclude writable school
EdFi.OdsApi.Models.Test_Profile_Resource_Excludeonly.School_Writable newWritableSchool = new EdFi.OdsApi.Models.Test_Profile_Resource_Excludeonly.School_Writable();
newWritableSchool.setId("999999");
newWritableSchool.setNameOfInstitution("The New School");
newWritableSchool.setSchoolId(999998);
newWritableSchool.setStateOrganizationId("XYZ");

// Post the new school
excludedSchoolApi.postSchools(newWritableSchool);
RestResponse<List<EdFi.OdsApi.Models.Test_Profile_Resource_Includeonly.School_Readable>> postModificationsResponse = includedSchoolApi.getSchoolsAll(null, null); 
System.out.println("Response code of profile include readable SchoolApi.GetAll() is " + preModificationsResponse.getStatus()); 
System.out.println("Results of profile include readable GetAll() after modifications: ");

 
for (EdFi.OdsApi.Models.Test_Profile_Resource_Includeonly.School_Readable school : postModificationsResponse.readEntity())
{ 
    System.out.println("Name - " + school.getNameOfInstitution() + " Id - " + school.getId()); 
}

  11. Add the following references to the top of the test.java file. Save the file. 

    import java.util.List;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Response;
import EdFi.OdsApi.Models.Test_Profile_Resource_Includeonly.*;
import EdFi.OdsApi.Models.Test_Profile_Resource_Excludeonly.*;
import EdFi.OdsApi.Sdk.BearerTokenAuthenticator;
import EdFi.OdsApi.Sdk.CertificateValidationDisabler;
import EdFi.OdsApi.Sdk.RestApiTokenRetriever;
import EdFi.OdsApi.Sdk.RestResponse;
import EdFi.OdsApi.Sdk.TokenRetriever;

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:

INSERT INTO [EdFi_Security].[dbo].[ClaimSetResourceClaims]
  (Action_ActionId, ClaimSet_ClaimSetId,ResourceClaim_ResourceClaimId)
  VALUES (3,1,6)
 
INSERT INTO [EdFi_Security].[dbo].[ClaimSetResourceClaims]
  (Action_ActionId, ClaimSet_ClaimSetId,ResourceClaim_ResourceClaimId)
  VALUES (1,1,6)

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
  • Post
  • Put

  • No labels