Using Code Generation to Create an SDK
This section outlines how to use code generation to create an Ed-Fi API Client SDK using a Windows environment targeting C#.
Ed-Fi API v8 metadata endpoints return documents adhering to the OpenAPI v3.0
specification. The available specification documents are listed at
http://localhost:8080/api/metadata/specifications; the resources specification
for a local deployment is:
http://localhost:8080/api/metadata/specifications/resources-spec.json
Step 1. Install Latest Version of Java
The code generation leverages Java, though it does output C# code. Thus you need a compatible JDK v11 or higher: Oracle Java, Adoptium (open source).
Step 2. Download the OpenApi Codegen JAR File
Download the latest version of the OpenApi Codegen JAR 7.19.0. Windows users can use Invoke-WebRequest in PowerShell 3.0+.
Invoke-WebRequest -OutFile openApi-codegen-cli.jar `
https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.19.0/openapi-generator-cli-7.19.0.jar
For more information and download options visit https://github.com/OpenAPITools/openapi-generator.
When generating an SDK using the OpenApi CodeGen resources in a language other than C# or Java and there are profiles defined in the OpenAPI specification file, be sure to verify that the proper contentTypes were created during the code generation.
Step 3. Generate the SDK Source Files
The SDK source files are generated from the API's OpenAPI specification
documents via a few simple PowerShell commands. You can see the available
specification documents at http://localhost:8080/api/metadata/specifications.
java -jar <openapi-generator-jar-path> generate -g csharp -i <swagger-json-url> `
--additional-properties targetFramework=net10.0,netCoreProjectFile=true --skip-validate-spec
A detailed description of the switch options can be found at https://github.com/OpenAPITools/openapi-generator.
To generate SDK source files, navigate to the folder containing openApi-codegen-cli.jar and run the following commands in PowerShell 3.0+. The Ed-Fi API publishes two core specification documents — the resources specification (which includes core and extension resources) and the descriptors specification — so the SDK is generated from each in turn, into segregated namespaces:
Resources (core and extensions)
java -jar openApi-codegen-cli.jar generate -g csharp `
-i http://localhost:8080/api/metadata/specifications/resources-spec.json `
--api-package Api.Resources --model-package Models.Resources -o ./csharp `
--additional-properties packageName=EdFi.OdsApi.Sdk,targetFramework=net10.0,netCoreProjectFile=true `
--global-property modelTests=false --global-property apiTests=false --skip-validate-spec
Descriptors
java -jar openApi-codegen-cli.jar generate -g csharp `
-i http://localhost:8080/api/metadata/specifications/descriptors-spec.json `
--api-package Api.Descriptors --model-package Models.Descriptors -o ./csharp `
--additional-properties packageName=EdFi.OdsApi.Sdk,targetFramework=net10.0,netCoreProjectFile=true `
--global-property modelTests=false --global-property apiTests=false --skip-validate-spec
Profiles and Change Queries
The resources and descriptors specifications describe the full API surface. If your API client is assigned an API profile, generate from that profile's specification instead, so that the SDK uses the profile's content types and constrained models:
http://localhost:8080/api/metadata/specifications/profiles/{profileName}/resources-spec.json
To call the Change Queries API (for example,
/changeQueries/v1/availableChangeVersions), generate from its specification
at http://localhost:8080/api/metadata/changequeries/v1/swagger.json. The
/metadata/specifications listing includes the profile and Change Queries
specifications that are available on your host.
Wait for the OpenAPI CodeGen to finish generating code. A Visual Studio Solution named EdFi.OdsApi.Sdk.sln will be created with the SDK artifacts.
Step 4. Use the SDK in a Sample C# Program
Download the sample: Sample Console Application project.
The sample project was written for ODS/API v7.3 and doesn't work as-is with Ed-Fi API v8. After you download it in step 2 below, edit it as follows:
- In
EdFi.OdsApi.SdkClient.csproj, give theCommandLineParserpackage reference a version:<PackageReference Include="CommandLineParser" Version="2.9.1" />. The sample's original repository sets that version centrally, so the version is missing once you copy the project into your solution. - In
Program.cs, change theHttpClientBaseAddressfrom{url}/data/v3to{url}/data. If your host uses tenant or route qualifier segments, include them before/data(see API Routes). - Replace the
EdFi.OdsApi.Sdk.Apis.AllandEdFi.OdsApi.Sdk.Models.Allimports with the namespaces generated in Step 3, such asEdFi.OdsApi.Sdk.Api.ResourcesandEdFi.OdsApi.Sdk.Models.Resources. EdFiTools/Authentication/TokenRetriever.csrequests a token from{url}/oauth/token, which the Ed-Fi API serves when--urlis the API base URL (for example,http://localhost:8080/api). If your host gives you a different token URL, point the token request at that URL instead.
-
Open the generated EdFi.OdsApi.Sdk.sln in Visual Studio.
-
Download the sample Console Application project from the link in the note above, place it in your solution directory, and make the edits listed in the warning above.
-
In the Solution Explorer, right-click on the solution and add a reference to the sample project that you downloaded in the previous step.
-
Right-click on EdFi.OdsApi.SdkClient > Set as Startup Project.
-
Right-click EdFi.OdsApi.SdkClient Dependencies node and click Add Project Reference.
-
In the Add Reference > Projects tab, select EdFi.OdsApi.Sdk, and then click OK.
-
Right-click EdFi.OdsApi.SdkClient > Properties > Debug > Open debug launch profiles UI and set the command line arguments. Use the template below, substituting your API base URL, client key, and client secret:
--url <Ed-Fi API Base URL> --key <client key> --secret <client secret> -
Run the application and you should see the following results:
Fetching student records 0 through 100 of 960Fetching student records 100 through 200 of 960Fetching student records 200 through 300 of 960Fetching student records 300 through 400 of 960Fetching student records 400 through 500 of 960Fetching student records 500 through 600 of 960Fetching student records 600 through 700 of 960Fetching student records 700 through 800 of 960Fetching student records 800 through 900 of 960Student: 604821, Tyrone, DodolphStudent: 604822, Lisa, WoodsStudent: 604823, Jill, RamirezStudent: 604824, Tracy, ColemanStudent: 604825, Lisa, WoodsStudent: 604826, Dale, BiennezStudent: 604827, Orozco, Peter_of_PrattStudent: 604828, April, OwenStudent: 604829, Rick, SheltonStudent: 604830, Peter_of_Pratt
With that, you're done!
If you're working with a specific platform host, a great next step is to use these same techniques to generate an SDK for that deployment. 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.