Identification

Does your organization host one or more Ed-Fi ODS/API instances?

• yes: 6
• no: 4

Do your organization write code to interact with the Ed-Fi ODS/API?

• yes: 10
• no: 0

Feature Usage - Hosts

Which of these ODS/API features do you use?

• Profiles - for restricting data access
  • Both read and write
  • Not using: 1
  • Some usage: 3
  • Critical usage: 1
• Profiles - for performance benefit
  • There are fewer attributes in the GET request
  • Not using: 4
  • Some usage: 1
  • Critical usage: 0
• Extensions
  
  • Not using: 2
  • Some usage: 2
  • Critical usage: 1
• Enable metadata / Open API spec 
  • Not using: 2
  • Some usage: 1
  • Critical usage:  2

Feature Usage - Client

Which of these ODS/API features do you use?

• Change Queries
  
  • Not using: 5
  • Some usage:  2
  • Critical usage:  2
• Link in the HTTP response
  •  
  • Not using: 4
  • Some usage:  3
  • Critical usage:  2
    

    "Critical" from 2 SIS vendors

    "Some" from a mix of groups

    More use than hypothesized

• PUT requests - instead of DELETE & POST
  • Some organizations choose to DELETE  and then re-POST modified records, instead of using PUT. Commonly this is to avoid extra coding logic around disallowed natural key updates (e.g. no updating a StudentUniqueId ).
  • Not using: 3
  • Some usage:   5
  • Critical usage:  1
• ETags and If-Match  header
  
  • Not using: 6
  • Some usage:  2
  • Critical usage:  1
• Data model information list at /api
  
  • Not using: 1
  • Some usage:   3
  • Critical usage:  4
• XSD endpoint
  
  • Not using: 6
  • Some usage:  2
  • Critical usage:  0
• Dependencies endpoint
  
  • Not using: 2
  • Some usage:  3
  • Critical usage:  3
• Enrollment Composite
  • Not using: 5
  • Some usage:  2
  • Critical usage:  0
• Identity Pass-through
  • Not using: 4
  • Some usage:  2
  • Critical usage:  2
• Location header - storing the ID
  
  • Not using: 3
  • Some usage:  2
  • Critical usage:  3

Strictness

How important are the following to you as requirements for an Ed-Fi API?

• Strict JSON payload validation
  • e.g. reject extra properties
    
  • Why? Someone might have a typo on an optional property and never realize because it was accepted but thrown away
  • Must not: 1
  • Could: 4
  • Should: 2
  • Must: 1
    

    In TAG discussion, found some valid reasons that we ought to allow this.

• Require a DateTime to include time
  • Most validators require the time component, though some systems will infer it as midnight
  • Must not: 1
  • Could: 4
  • Should: 2
  • Must: 1
• Store time in UTC
  • Otherwise, whose timezone is it?
  • Must not: 1
  • Could: 7
  • Should: 2
  • Must: 0
    

    Should instead have asked about storing the offset. That's what the ODS/API does today and what we should encourage.

• Case sensitive resources names / attributes
  • /ed-fi/classPeriods is different from /ed-fi/ClAsPeriODs 
  • ?schoolId=1234  is a valid query but ?sCHOoLid=1234  is not
  • Should not be (or not only) dependent on database technology
  • Must not: 3
  • Could: 3
  • Should: 3
  • Must: 1
    

    Much more mixed opinions than on the next question. How many API frameworks can handle this easily?

• Case sensitive string values
  
  • ?firstName=John and ?firstName=JOHN  return different results
  • This is the default in PostgreSQL, but not in SQL Server
    • Modifying the database setting is harder than one would think
  • Must not: 4
  • Could: 4
  • Should: 1
  • Must: 0
    

    This is not a popular feature, though it exists in PostgreSQL today. Be flexible, but discourage in new implementations.

Proposed Additions

How important are the following to you as requirements for an Ed-Fi API? All would be "COULD HAVE" features at this point, so that existing implementations do not immediately fall foul.

• Standardized error codes
  • Why? Because error handling is hard today and too dependent on implementation details (like which database is being used).
  • Details are being worked out; in short, every 400 response would have a code that is independent of implementation, and can be translated to something meaningful to a human operating a source system.
  • No: 0
  • Neutral: 1
  • Yes: 9
    

    Very popular!

• Declare case sensitivity in metadata
  
  • New idea for future releases
    
  • No: 2
  • Neutral: 3
  • Yes: 5
• Delete by natural key
  • e.g. instead of DELETE .. /ed-fi/students/abcd1234xyz then DELETE ../ed-fi/students/studentUniqueId=1234
  • Particularly useful for organizations who are not storing the Ed-Fi unique identifier (abcd1234xyz in the example above).
  • No: 1
  • Neutral: 2
  • Yes: 7
• For a GET query, add sorting field(s) and direction(s)
  • Exact format to be determined
  • No: 0
  • Neutral: 5
  • Yes: 5

Changes and Deletions

Any heartburn over the following proposed changes to the API Standard?

1. Remove most references to XML files (except possibly the XSD file endpoint)
   1. No: 2
   2. Neutral: 6
   3. Yes: 1
2. Today: "It is recommended that Descriptors be read-only from the API's perspective. However, an implementation may allow them to be created using POST and updated using PUT." Tomorrow: change to recommend (SHOULD) allowing all four operations for Descriptors: POST, GET, PUT, and DELETE, so that the API can be the single point of entry for data (no direct database access).
   1. No: 2
   2. Neutral: 2
   3. Yes: 6
3. Add that Descriptors should be searchable by querystring, just like Resources are.
   1. No: 1
   2. Neutral: 6
   3. Yes: 3
4. Change reference to PATCH to say that an Ed-Fi API should not implement the PATCH verb. We don't have it today, and anyone adding it would risk significant fracturing of client code unless all add that support.
   1. No: 3
   2. Neutral: 5
   3. Yes: 1
5. Remove references to search operators other than = (other terms aren't allowed in a URL query string).
   1. No: 2
   2. Neutral: 5
   3. Yes: 2
6. These API guidelines are realized through a particular API specification. That specification will have search terms in it that will be flattened, and an Ed-Fi API MUST support those terms. Example: although a JSON body might have { "schoolReference":  { "schoolId": 1234 } }, the query should be ?schoolId=1234, not ?schoolReference.schoolId=1234, and this format must be expected of all implementations.
   1. No: 1
   2. Neutral: 5
   3. Yes: 3
7. Remove the notion of field selectors, such as  /students/{id}?fields=firstName,lastSurname.
   1. No: 4
   2. Neutral: 5
   3. Yes: 1
      

      I should revisit this. How would it work for nested JSON documents? Is it feasible in the ODS/API? What happens if people rely on it in one implementation and another doesn't have it?

8. Add something about an API could support keyset/cursor paging as an alternative to limit/offset style paging.
   1. There is a significant performance concern on many databases when you try to use limit/offset paging after around 10,000 items.
   2. No: 2
   3. Neutral: 2
   4. Yes: 6
9. Change the paging to state that limit / offset SHOULD be implemented, not MUST be implemented.
   1. Given the performance concern, it would make sense to allow a host to disable access to this type of paging.
   2. No: 2
   3. Neutral: 5
   4. Yes: 3
10. Expand the list of HTTP status codes to include all available, highlighting a few additional relevant 5xx codes.
    1. No: 2
    2. Neutral: 3
    3. Yes: 5
11. Remove all references to three-legged OAuth, users, user roles, etc. This API is only for system-to-system interaction, not for direct end-user support. Don't forbid it, just leave it out.
    1. No: 2
    2. Neutral: 6
    3. Yes: 2

Final Thoughts

Free text comment box

Name

Organization

Results

Live Survey

Survey Results Page

→ Exported results: API Standard SIG - September 2023 Survey(1-10).xlsx