Skip to main content
Version: 8

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#.

info

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.

info

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​

note
warning

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 the CommandLineParser package 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 the HttpClient BaseAddress from {url}/data/v3 to {url}/data. If your host uses tenant or route qualifier segments, include them before /data (see API Routes).
  • Replace the EdFi.OdsApi.Sdk.Apis.All and EdFi.OdsApi.Sdk.Models.All imports with the namespaces generated in Step 3, such as EdFi.OdsApi.Sdk.Api.Resources and EdFi.OdsApi.Sdk.Models.Resources.
  • EdFiTools/Authentication/TokenRetriever.cs requests a token from {url}/oauth/token, which the Ed-Fi API serves when --url is 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.
  1. Open the generated EdFi.OdsApi.Sdk.sln in Visual Studio.

  2. 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.

  3. In the Solution Explorer, right-click on the solution and add a reference to the sample project that you downloaded in the previous step.

  4. Right-click on EdFi.OdsApi.SdkClient > Set as Startup Project.

  5. Right-click EdFi.OdsApi.SdkClient Dependencies node and click Add Project Reference.

  6. In the Add Reference > Projects tab, select EdFi.OdsApi.Sdk, and then click OK.

  7. 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>
  8. Run the application and you should see the following results:

    Fetching student records 0 through 100 of 960

    Fetching student records 100 through 200 of 960
    Fetching student records 200 through 300 of 960
    Fetching student records 300 through 400 of 960
    Fetching student records 400 through 500 of 960
    Fetching student records 500 through 600 of 960
    Fetching student records 600 through 700 of 960
    Fetching student records 700 through 800 of 960
    Fetching student records 800 through 900 of 960

    Student: 604821, Tyrone, Dodolph
    Student: 604822, Lisa, Woods
    Student: 604823, Jill, Ramirez
    Student: 604824, Tracy, Coleman
    Student: 604825, Lisa, Woods
    Student: 604826, Dale, Biennez
    Student: 604827, Orozco, Peter_of_Pratt
    Student: 604828, April, Owen
    Student: 604829, Rick, Shelton
    Student: 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.