API SDK for Java

This section outlines how to use code generation to create an Ed-Fi ODS / API Client SDK using a Windows environment to create a Java client. The high-level steps are:

Each step is outlined in detail below.

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.
  (http://www.oracle.com/technetwork/java/javase/downloads/index.htm)
• Install the Scala Build Tool (sbt).
  (http://www.scala-sbt.org/release/tutorial/Installing-sbt-on-Windows.html)
• Set the Windows PATH environment variable to find the jdk bin directory.

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. Follow these steps to download the repository archive and extract it:

• Navigate to https://github.com/Ed-Fi-Alliance/Ed-Fi-ODS-API-SDK/tree/v2.0 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 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 the 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.0). 
• After the extractions are complete, rename the folder to remove the “-2.0” 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 SDK Source Files

The SDK source files are generated via a few simple command line steps. First, run the command below to generate SDK source files:

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}

A brief description of the switch options follows:

• target-language. csharp or java (we'll use java).
• --url. https://{Domain root of API}/metadata/{section}/api-docs (where section is typically  "resource", "descriptors", or "types").
• --baseDir. The local folder where you would like the code files to be created.
• --apiPackage. Namespace for the classes that expose methods that map to resources and verbs (e.g., EdFi.OdsApi.Api).
• --helperPackage. Namespace for the general SDK classes that support the Ed-Fi ODS / API interaction (e.g., EdFi.OdsApi.Sdk).
• --modelPackage. Namespace for the entities that are exchanged with the Ed-Fi ODS / API (e.g., EdFi.OdsApi.Models).

Next, navigate to C:\Ed-Fi-ODS-API-SDK\target\scala-2.10 and run the following commands to generate Java SDK source files for the Ed-Fi-hosted instance at https://api.ed-fi.org:

java -jar sdk-generate.jar java --url http://api.ed-fi.org/api/metadata/resources/api-docs --baseDir C:\Ed-Fi-ODS-API-SDK\JavaSDK --apiPackage EdFi.OdsApi.Api --helperPackage EdFi.OdsApi.Sdk --modelPackage EdFi.OdsApi.Models
java -jar sdk-generate.jar java --url http://api.ed-fi.org/api/metadata/descriptors/api-docs --baseDir C:\Ed-Fi-ODS-API-SDK\JavaSDK --apiPackage EdFi.OdsApi.Api --helperPackage EdFi.OdsApi.Sdk --modelPackage EdFi.OdsApi.Models
java -jar sdk-generate.jar java --url http://api.ed-fi.org/api/metadata/types/api-docs --baseDir C:\Ed-Fi-ODS-API-SDK\JavaSDK --apiPackage EdFi.OdsApi.Api --helperPackage EdFi.OdsApi.Sdk --modelPackage EdFi.OdsApi.Models

Step 5. Use the SDK in a Sample Java Program

We'll use the Eclipse IDE for this exercise, but analogous steps will generally work in other development environments.

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. Save the file.
   
   
   
5. Create the following packages under src/main/java:

   • EdFi.OdsApi.Api

   • 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\OdsApi) 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.
   
   
   
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 code 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://api.ed-fi.org/api";
    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://api.ed-fi.org:80/api/api/v1.0/2015");
    
    // GET schools
    SchoolsApi api = new SchoolsApi(target);
    
    // RestResponse wraps a JAX-RS Response to provide a properly typed readEntity() method
    RestResponse<List<School>> response = api.getSchoolsAll(null, null); // offset, limit
    
    int httpReponseCode = response.getStatus(); // returns Response.Status.OK
    System.out.println("Response code is " + httpReponseCode);
    
    for (School school : response.readEntity()) 
    {
    	System.out.println(school.getNameOfInstitution());
    }

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 EdFi.OdsApi.Api.SchoolsApi;
    import EdFi.OdsApi.Models.School;
    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;

12. Select the test.java class and run it as a java application. The console will display the result code and the names of the sample schools in the database.
    

Finished!

This exercise leveraged a publicly available instance of the API which contains the surface for a core implementation. If you're working with a specific platform host and you already have a key/secret pair, a great next step is to use these same techniques to generate an SDK for that platform. If the platform host has extended the data model, your new code will automatically include those structures in the data access components in the generated code.