API Standard SIG - 2023-07-27

Owned by Ann Su
Last updated: Jul 31, 2023 by Stephen Fuqua
2 min read

Participants

 Click here to expand...


First NameLast NameOrganization
DavidClementsEd-Fi Alliance
EdwardDedicPowerSchhol
RoshDhanawadeEducation Analytics
StephenFuquaEd-Fi Alliance
JasonGainesKeen Logic
GregGilmanJmcinc
Jean-FrancoisGuertinEdWire
SherodKeenKeen Logic
LisaLevyEdsembli
AlexLooneyACT
JaredMannRenaissance
VinayaMayyaEd-Fi Alliance
OscarOrtegaEdupoint Eudcational Systems
MaxPaulsonDenver Public Schools
KristiPruettRenaissance
KirkPrybilACT
TomReitzEA
JenSauroInfinite Campus
MarkTenHoorEducation Analytics
MustafaYilmazEd-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
    • (tick) 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)
      • (error) "v3" in the URL does not need to be standardized.
    • Dependencies
      • (tick) 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
      • (warning) 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.
      • (error) Do not standardize the Open API version
    • Read Only Properties
      • (error)  Do not try to standardize underscore prefix for read-only properties in an Ed-Fi API
      • (tick) Do ensure that the Swagger / Open API documents properly label properties as readonly
      • (tick) 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
    • (tick) 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.
    • (error) Do not remove any of the existing properties (codeValue, shortDescription, description, effectiveBeginDate, effectiveEndDate).
    • (tick) Be more prescriptive about using human readable codeValues, not numbers or random strings.
    • (warning) Consider removing the xyzDescriptorId values from ODS/API if possible, or document them as a could have property on Descriptors.
    • (warning) Discourage allowing Descriptor natural key updates.  ODS-5418 - Getting issue details... STATUS
    • (tick) 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