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.
SDK Reference
- Ian Christopher
- Chris Moffatt (Deactivated)
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/api"; const string clientKey = "RvcohKz9zHI4"; const string clientSecret = "E1iEFusaNf81xzCxwHfbolkC"; // RestSharp dependency, install via NuGet var client = new RestClient("https://api.ed-fi.org/api/api/v2.0/2016");
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 which 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.
Schools Resource | SchoolsApi |
---|---|
- | SchoolsApi(IRestClient client) |
List of Schools | GetSchoolsAll(offset, limit) |
List of Schools | GetSchoolsAll(offset, limit, schoolId, localEducationAgencyId, type, charterStatusType, titleIPartASchoolDesignationType, magnetSpecialProgramEmphasisSchoolType, administrativeFundingControlDescriptor, internetAccessType, charterApprovalAgencyType, charterApprovalSchoolYear) |
Single School | GetSchoolByKey(schoolId, IfNoneMatch) |
Single School | GetSchoolsById(id, IfNoneMatch) |
- | PostSchools(school) |
- | PutSchool(id, IfMatch, school ) |
- | DeleteSchoolById(id, IfMatch) |
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.