Standards: Do we need them?

There are standards emerging that compensate for many of the perceived missing elements from previous API offerings -- JSON-LD, HAL, RDF, WADL, etc. All solve different problems.

The question: Do we need to reintroduce many of the complexities that these standards bring along? Are they problems they solve worth the impact to delivering good APIs?

Conveners

• Chris Hatton
• Todd Fredrich

Time

• Day 2 (10:30-12:00)

Attendees

• [Carl Zetie] (mailto:[email protected])

Agenda

• Contracts - WADL, JSON Schema
• Versioning - URL, Header, Content-type
• Linkability - ATOM, JSON-LD, HAL
• Content-Type Negotiation
• Authentication - OAuth, SAML, OpenID

Notes

Preamble

Swing of the pendulum from SOAP => REST => {swinging back}?

Contracts

• WADL - Been around the longest, lack of broad adoption
• JSON Schema - Validation, hand-written, more weakly-typed, start minimally
• No tooling yet ... WSDL used to be auto-generated because SOAP had the tooling
• Depends on number of consumers and stability requirements
• Introspection could reduce need for contract
  • Interface is contract
• Value in contrac-first design (e.g. protocaol buffers)
• Doesn't capture call order (semantics) of contract. Definition might not be enough
• Tool generation and testing (after-the-fact ... code is always right)

Versioning

• Needed for backwards compatibility
• In header: mechanism for load-balancing
• In URL:
  • Negative effect on linkability
  • Good for versioning entire service/app
• Content-type negotiation:
  • Versions payload, still the same resource
  • [Proposal for versioning in the content-type] (http://toddfredrich.com/rest-api-versioning-good-bad-or-ugly.html)
• Default Version:
  • Default to latest stable (common)
  • Default to oldest (safest)
  • No default ... require a version from Day 1?
  • Provide deprecation warnings ... email to registered developer

Linking

• Depends on service consumer library
• Graph w/ nearest neighbors
• "self" -> identifies where obtained (in case of a save)
• w3c Linked Data spec w/ IBM at OASIS [OSLC] (http://http://www.oasis-oslc.org/)
• JSON-LD
  • Schema + Extensions + Linking
• HAL
• Siren
• Collections.js

Content-types

• More than 'application/json'
• Requires tools to support
• If domain-specific, types are more valuable
• Less-constrained domain -> less value from content types
• Use registered types for common elements

Authentication

• Despite problems, OAuth seems to be the best current option (broad general adoption)
• For SSO, SAML works well
  • Ping Federate good COTS offering
• HttpSignature from Joyent ?
• Auth.io ?

Mobile

• Most using bearer tokens
• Also Hashed user|password|salt as token