API SDK for C#

This section outlines how to use code generation to create an Ed-Fi ODS / API Client SDK using a Windows environment targeting C#. 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. In case you're wondering: the code generation leverages Java, but it does output C# code.

• 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 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 csharp).
• --url. https://{Domain root of API}/metadata/{section}/api-docs (where section is generally "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 C# SDK source files for the Ed-Fi-hosted instance at https://api.ed-fi.org:

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

Step 5. Use the SDK in a Sample C# Program

1. Open up Visual Studio and create a new project. Choose the type Visual C# > Console Application. Name the project ‘EdFiClientSDK’.
   
   
   
2. Add three folders to the project. One for each of the packages generated from the previous step. The folders should be named ‘Api’, ‘Models’, and ‘Sdk’.
   
   
   
3. Right click on each of the folders and add the existing classes for each package. The files can be found at the following location. C:\Ed-Fi-ODS-API-SDK\CSharpSDK\src\EdFi\OdsApi. Be sure to select all of the generated SDK files for each package.
   
   
4. Use the Package Manager Console to install the RestSharp library. At the PM> prompt, enter ‘install-package restsharp’.
   
   
   

5. Edit the Program.cs file and paste the following into the Main method. The client and key are using a publicly available sandbox environment with sample data hosted by the Ed-Fi Alliance.

   // Trust all SSL certs -- needed unless signed SSL certificates are configured.
   System.Net.ServicePointManager.ServerCertificateValidationCallback =
       ((sender, certificate, chain, sslPolicyErrors) => true);
   
   // Oauth configuration
   var oauthUrl = "http://api.ed-fi.org/api";
   var clientKey = "5iqu6lX4JJAS";
   var clientSecret = "EytEoZqr2a0n3jMD5qsyUyiB";
   
   // RestSharp dependency, install via NuGet
   var client = new RestClient("http://api.ed-fi.org:80/api/api/v1.0/2015");
               
   // TokenRetriever makes the oauth calls
   var tokenRetriever = new TokenRetriever(oauthUrl, clientKey, clientSecret);
   
   // Plug Oauth into RestSharp's authentication scheme
   client.Authenticator = new BearerTokenAuthenticator(tokenRetriever);
   
   // GET schools
   var api = new SchoolsApi(client);
   
   var response = api.GetSchoolsAll(null, null); // offset, limit
   
   var httpReponseCode = response.StatusCode; // returns System.Net.HttpStatusCode.OK
   var schools = response.Data;
   
   Console.WriteLine("Response code is " + httpReponseCode);
    
   foreach (var school in schools)
   {
       Console.WriteLine(school.nameOfInstitution);
   }

6. Add the following using statements at the top of the file:

     using EdFi.OdsApi.Sdk;
     using EdFi.OdsApi.Models;
     using RestSharp;

7. Build the project and run it without debugging (Ctrl+F5) and you should see the following results:
   

With that, you're done!

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.