SDK Reference

This section provides a quick reference to some key points related to the code-generated SDK. This document uses the SDK as generated for C# for its examples, but most of the principles apply equally to the code-generated Java SDK.

OAuth Sessions

The sample code provided with the SDK hides the complexity involved in authorizing a client application by using TokenRetrieve and BearerTokenAuthenticator classes. When configured with a valid client key and secret, the work needed to authenticate a client application is trivial, and transparent to the RestClient. (Compare this to the step-by-step OAuth steps we covered earlier in the Authentication section of this documentation.)

When creating a client against the sandbox hosted by the Ed-Fi Alliance, the following values can be used:

// Oauth configuration
const string oauthUrl = "https://api.ed-fi.org/v2.6.0/api/";
const string clientKey = "RvcohKz9zHI4";
const string clientSecret = "E1iEFusaNf81xzCxwHfbolkC";

// RestSharp dependency, install via NuGet
var client = new RestClient("https://api.ed-fi.org/v2.6.0/api/api/v2.0/2018/");

RestClient Object Lifetime

Each RestClient instance maintains its authentication for the lifetime of the object. For this reason, it is unnecessary and inefficient to create a new RestClient for each API call. You should maintain a RestClient instance for every call in a single session, and create a new RestClient only when a new security context is needed (i.e., whenever you have to pass in a new key and secret). Changes in data model context such as year or profile that do not change the authentication context do not require a new RestClient instance.

For most applications, this means that you should not need to create more than one RestClient in most circumstances. 

Synchronous Client

The SDK generates code that provides a synchronous (blocking) client. Asynchronous clients can be created, but must be done manually by your application.

Resources

The generated SDK includes strongly typed resources for each type in the Swagger documentation site. By default, the resources are generated in a *.Models namespace that will differ depending upon the root namespace provided during SDK generation.

The Resource APIs

The generated SDK includes a strongly typed entry point corresponding to each method in the Swagger documentation site. The individual APIs in the SDK correspond to resources and are generated in a *.Api namespace. Most resources have the same set of methods corresponding to the REST methods for that resource in the API. For example, the Schools resource corresponds to a SchoolsApi class that has the following methods. 

The "Other" API Endpoints

The BulkOperationsApi class may be used to post bulk XML data. The IdentitesApi class is used to interact with an installed identity system. Both of these classes work similarly to the generated resource APIs.