/
API Standard SIG - 2023-07-27

API Standard SIG - 2023-07-27

Jul 31, 2023

Participants

 

First Name

Last Name

Organization

David

Clements

Ed-Fi Alliance

Edward

Dedic

PowerSchhol

Rosh

Dhanawade

Education Analytics

Stephen

Fuqua

Ed-Fi Alliance

Jason

Gaines

Keen Logic

Greg

Gilman

Jmcinc

Jean-Francois

Guertin

EdWire

Sherod

Keen

Keen Logic

Lisa

Levy

Edsembli

Alex

Looney

ACT

Jared

Mann

Renaissance

Vinaya

Mayya

Ed-Fi Alliance

Oscar

Ortega

Edupoint Eudcational Systems

Max

Paulson

Denver Public Schools

Kristi

Pruett

Renaissance

Kirk

Prybil

ACT

Tom

Reitz

EA

Jen

Sauro

Infinite Campus

Mark

TenHoor

Education Analytics

Mustafa

Yilmaz

Ed-Fi Alliance

Support: Ann Su, Ed-Fi Alliance

Agenda

  • Kickoff

  • Metadata

  • Descriptors

Materials

Notes

More detailed notes were taken in the presenter notes section of the slide deck. Please download the deck above to see those detailed notes. The notes below are a summary of recommendations and open questions.

The recommendations below reflect @Stephen Fuqua 's takeaways from the conversation.

  • Kickoff

    •  Use "Ed-Fi API" as the name of the (generic) interface, and products that are an implementation of the Ed-Fi API should have another name. Examples of product names: Ed-Fi ODS/API, Ed-Fi Meadowlark API.

  • Metadata

    • API Standards Version

      • Unlikely that one API implementation would support multiple API Standard versions.

      • No prospect, at this time for creating a v4 (this SIG's outcomes likely become revision 3.2)

      • "v3" in the URL does not need to be standardized.

    • Dependencies

      • An Ed-Fi API should have the JSON representation of Dependencies and could have the GraphML representation.

      • Related: 

        ODS-4799 - Getting issue details... STATUS

    • Open API

      • Try to change swagger.json to Open API version 3, create SDK, and see how different it is from today's SDK to make sure nothing breaks.

        • So long as the API itself hasn't changed, the older SDK and newer SDK ought to be compatible, even if the generated code is different.

      • Do not standardize the Open API version

    • Read Only Properties

      •   Do not try to standardize underscore prefix for read-only properties in an Ed-Fi API

      • Do ensure that the Swagger / Open API documents properly label properties as readonly

      • Prefer being more strict about overposting: an Ed-Fi API should reject a POST or PUT request that contains properties that are not defined on the API model.

        • If we say must then this would be a breaking change to the API Standard, making all current versions of the ODS/API incompatible.

  • Descriptors

    • Change the guidance about PUT/POST: An Ed-Fi API should support the Descriptors API definition for modifying descriptors, with an authorization model appropriate to the implementation needs.

    •  Do not remove any of the existing properties (codeValue, shortDescription, description, effectiveBeginDate, effectiveEndDate).

    • Be more prescriptive about using human readable codeValues, not numbers or random strings.

    • Consider removing the xyzDescriptorId values from ODS/API if possible, or document them as a could have property on Descriptors.

    • Discourage allowing Descriptor natural key updates. 

      ODS-5418 - Getting issue details... STATUS

    • Add _etag and _lastModifiedDate readonly properties to the definition.

Next meeting: 2023-08-24

Agenda:

  • Query Support

    • Searching: e.g. GET /ed-fi/studentSchoolAssociations?studentUniqueId=ABCXYZ

    • Selectors

    • Paging

  • HTTP Status Codes

  • Security

    • Authentication

    • Authorization

    • Non-repudiation