Identification

Are you responding as a...

...

• Vendor who accesses Ed-Fi API instances?
• Host who manages Ed-Fi API instances?
• Education Agency who relies on an Ed-Fi API?

Feature Usage

Which of these ODS/API features do you use?

...

• Profiles - for restricting data access
  • Both read and write
• Profiles - for performance benefit
  • There are fewer attributes in the GET request
• Extensions
• Change Queries
• link  in the HTTP response
  
• 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 ).
• ETags and If-Match  header
  
• Data model information list at /api
  
• XSD endpoint
  
• Dependencies endpoint
  
• Enrollment Composite
• Identity Pass-through
• Location header - storing the ID
  

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
• Require a DateTime to include time
  • Most validators require the time component, though some systems will infer it as midnight
• Store time in UTC
  • Otherwise, whose timezone is it?
• 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
• 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

Proposals

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.

(Likert scale with options: must not, could, should, must)don't it! neutral, yes please!)

• 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.
• Declare case sensitivity in metadata
  
  • New idea for future releases
    
• 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).
• For a GET query, add sorting field(s) and direction(s)
  • Exact format to be determined

Changes and Deletions

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

(Each should be a separate question with a comment box to explain any concern; the question would have a choice of no concern, mild concern, stop!)

1. Remove most references to XML files (except possibly the XSD file endpoint)
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).
3. Add that Descriptors should be searchable by querystring, just like Resources are.
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.
5. Remove references to search operators other than = (other terms aren't allowed in a URL query string).
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.
7. Remove the notion of field selectors, such as  /students/{id}?fields=firstName,lastSurname.
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.
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.
10. Expand the list of HTTP status codes to include all available, highlighting a few additional relevant 5xx codes.
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.