TODO

The following are tasks -priority ordered- that need to be done to complete the API guidelines. Each task should be following with the plan and responsible to complete the task.

  • ✓ Consider using entity versions
  • ✓ Consider requiring schema.org (decision: schema.org not suitable)
  • ✗ Consider requiring another naming conventions
  • ✗ Lots of little edits (see list below)
  • ✗ Much more details around security (authentication, delegation, authorisation)
  • ✗ Create a summary for the busy developer.
  • ✗ Add more clarity around having multiple APIs acting together as one
  • ✗ Add more stuff about non-json responses.
  • ✗ Define a change procedure for these guidelines.
  • ✗ Recommendations for (semi-)public developer portal.
  • ✗ Consider adding information on testing
  • ✗ Volume filtering.
  • ✗ Bulk endpoint for mobile optimizations.
  • ✗ Streaming endpoints.
  • ✗ JSONP
  • ✗ CORS?

Lots of small edits

URL, URI
  • ✓ Documentation should point to HAL documentation
  • ✓ underscore means meta parameters (reserved for API)
  • ✓ X-HTTP-Method-override
  • ✓ _body parameters applies to every call
  • ✓ PATCH/DELETE not being supported by browsers => Remove
  • ✓ Clearer use of MUST/SHOULD/CAN (consistent)
  • ✓ _include/ _exclude needs major revamp
Resource Format
  • ✓ Add something about that RFC martin just mentioned (URL templates), MUST
  • ✓ Remove serialization from URLs
  • ✓ Language of errors more clear
  • ✓ Add status code as field for errors
  • ? _link.help.href is pointing to an invalid URL (and more URLs)
  • ✓ Link to type table
  • ? help.href vs describedby, don’t know why. For now just documented that it is so.
  • ✓ clarify the help page link
  • ✓ Add link to currying in HAL
  • ✓ Clarify section on custom link relation types
  • ✓ Fieldnames cannot be duplicate
  • ✗ Come up with field-names standard
Interaction
  • ✗ OPTION / HEAD calls missing
  • ✗ TRACE not supported (security)
  • ✗ Resource without etag => clarify body response is an error response
  • ✗ GZIP/Deflate
Documentation Requirements
  • ✗ Recommend order of headers, documentation tools
  • ✗ Clean up stuff at the bottom
  • ✓ Expand further
Versioning
  • ✓ Requires follow-up
Postponed:
  • ✗ DELETE call => No more fetch
GLOBAL:
  • ✓ HTTPS on all examples
  • ✗ fix all todos
  • ✓ re-do the documentation in RST