ApiCheckList

From DAP WG Wiki
Revision as of 15:40, 23 November 2011 by Dom (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

To ensure our APIs are of good quality and match our requirements:

  • run the WebIDL definitions in the WebIDL checker
  • for privacy-sensitive APIs, ensure that the API offers a way to provide as little information as the developer may need; ideally, it should be simpler to get less data
  • ensure that callback functions that don't take parameters just be described as "Function" (rather than using a custom interface that doesn't add any value). When using a more complex callback interface, make sure that it doesn't use [Callback=FunctionOnly] when [Callback] would suffice.
  • asyncronous operations need to be defined in terms of the HTML5 events loop (cf Robin's mail)
  • check that nullable interfaces are marked as such (cf change in Web IDL as of May 2011)
  • the API should be implementable in pure JavaScript to allow shims that mimic the API and provide fallback functionality

General Items

  • Be sure to include a requirements section in your document

Privacy & Security Considerations

  • if the API access depends on access control request, is there a need for discussing the persistence/revokation of the access control request?
  • if there are more than one sensitive API call, does the access control request cover all the calls? a subset of them? how are they grouped if so? is that grouping imposed to all user agents? can they subset it?
  • if the API access depends on access control request and requires further user interaction (e.g. a modal picker), what happens when requests are queued? (FIFO, LIFO, something else?)
  • indicate the link between the origin of the script and the top-level browsing context origin in terms of access control, and its potential impact on the UI
  • if the API allows for saving/removing data, how is that communicated to the user (in particular to approve it)?
  • don't include normative requirements for recipients of data; rather, refer to the privacy best practices
  • if the API has extensibility mechanisms (e.g. vendor prefixes, URI-based features), how do the security/privacy considerations apply to these extensions?
  • if permissions can be persisted, include requirement on revokation of permissions
  • if there is a get vs watch model, do the securiy/privacy considerations apply uniformly?