This document will enable developers to analyze the API and database changes between two versions of ODS / API 3.x releases and access the impact of upgrade. 

Viewing API endpoint and JSON payload changes

The ODS / API metadata defines the API endpoints and it can be downloaded from the ODS / API metadata endpoints. You can get them either from ed-fi public sandboxes in api.ed-fi.org or from local environment by downloading source code and building both versions one at a time. Downloaded metadata files can then be compared using file comparison tool to extract the metadata differences between the versions.

The following metadata endpoint includes metadata for core resources: https://api.ed-fi.org/{ods api version}/api/metadata/data/v3/ed-fi/swagger.json 

For example, https://api.ed-fi.org/v3.3.0/api/metadata/data/v3/ed-fi/swagger.json contains metadata for v3.3 release. 


For demonstration purpose here we will use Visual Studio to format JSON and to compare ODS / API versions v3.2 and v3.3. 

Step 1. Download the JSON metadata for desired ODS / API versions 

Download https://api.ed-fi.org/v3.2.0/api/metadata/data/v3/ed-fi/swagger.json and https://api.ed-fi.org/v3.3.0/api/metadata/data/v3/ed-fi/swagger.json 

Step 2. Use Visual Studio to format the JSON metadata file for clarity.

Open the JSON metadata file, Right-click on the file, choose Format Document. Do this for both files.

Step 3. Use Visual Studio to compare the metadata files.

Click View Other Windows > Command Window and type Tools.DiffFiles followed by the location of both JSON metadata files.

> Tools.DiffFiles "C:\MetadataFiles\swagger odsapi v32.json" "C:\MetadataFiles\swagger odsapi v33.json" 


You will see changes highlighted in the editor


Viewing database changes

ODS / API binary releases include sample data sets as Nuget packages at https://www.myget.org/feed/ed-fi/package/nuget/EdFi.Samples.Ods . The sample databases for the two ODS / API versions can be downloaded and compared using schema compare tools like SSDT. 

For demonstration purpose here we will compare database schema for ODS / API versions v3.2 and v3.3. 

Step 1. Download and deploy sample databases a SQL Sever instance

In order to see database schema changes, you will need both v3.2 and v3.3 ODS database versions in a SqlServer instance.  Download database packages for v3.2.0 and v3.3.0 releases. Extract the .bak files from the Nuget packages and use the MS SQL Server Management Studio (SMSS) to restore the databases in your SqlServer instance.

Step 2. Use Visual Studio SQL Server Data Tools (SSDT) to compare schema

Using Visual Studio with SQL Server Data Tools (SSDT) installed, you can perform a database schema comparison between the two database versions located in your SQL Server instance.

Step 2.a In Visual Studio, Click Tools SQL Server > New Schema Comparison


Step 2.b Select source and target schema to choose the restored databases for v3.2.0 and v3.3.0 on you SQLServer instance 


Step 2.c  Click on Options Menu on the schema compare editor to customize your schema compare options to focus on certain changes.  This allows you to ignore users, roles, indexes and other objects in databases. 


Step 2.d Click Compare. You can see the schema changes between two versions.

The green plus symbol in the following image shows some new columns to the existing tables.

The green plus symbol in the following image shows some new tables.







  • No labels