Consuming Media Types: Making Life Easier for API Clients

In this (sometimes lively) discussion, we talked about how much people use non-generic media types, i.e., other than application/json, application/xml). Turns out that not many people are using more specific or structured media types. Some of the problems (or perceived problems) that were brought up are as follows:

Problems

• In denial about distributed systems (see, for example, Mike Amundsen's blog entry about "Interoperability, not integration")
• Optimizing for API consumers to help them get their app up-and-running quickly, and to heck with longevity.
• No parser (library) available
  • HTML can be hard to parse, too (Mike Amundsen suggested using application/xhtml+xml to make this easier, with the plus that it looks like plain-old-XML that might avoid triggering fear).
    • Some ambiguous, amorphous fear of HTML variants
• Cheaper to just create new resources: instead of versioning the media types, and/or using a media type that is more flexible in the face of change, many companies seem to decide that it's easier to just create a new resource or set of resources. This seems to apply to the whole "version the whole API with a version number somewhere" issue as well.
• Chicken-and-egg problem: API consumers won't use more specific media types (e.g., HAL, Collection+JSON, SIREN, etc.) if there's no compelling reason. Server/API developers won't use those media types for fear of lack of acceptance. Libraries to make consuming those APIs easier won't be developed (or refined) if it's not used by a wider audience.

I asked people what media types they use:

• application/json
• application/xml
• text/csv
• (a line was drawn here to indicate that media types that follow are harder to consume)
• application/vnd.github.v3+json
• application/hal+[json|xml]
• application/collection+json
• application/vnd.siren+json
• application/atom+xml
• application/xhtml+xml

Benefits

We also listed benefits and/or ways to make the use of the "below the line" media types more approachable

• Loose coupling: to me, this is a key benefit, though it doesn't always seem to be recognized as a worthwhile benefit (see "in denial about distributed systems").
• Clients can be more dynamic: once the client is built around a more structured media type, specifically one that has links, the client can display options available and/or form elements completely based on what's return in the response body. This, to me, is the clear benefit of HATEOAS (aka Hypermedia APIs).

Making it more approachable

• Serve multiple media types, e.g., application/json and application/hal+json
  • It was argued that this could be a bad idea as it'd make it very easy for clients to simply use the "easier" media type and not be able to take full advantage of a type such as HAL.
• Create a media type proxy (e.g., translate generic application/json from a specific API provider to, say, application/vnd.siren+json) to promote the use of the conventions described by the media type.
• Providing libraries (SDKs) that make it easier to interact with
  • It was noted that the SDKs shouldn't make things too abstract, i.e., make sure that it's still clear to the user of the SDK that they're communicating over an imperfect network. This was also brought up in other sessions where SDKs were discussed, so seems to be a common theme.

Action Items

Brian (@landlessness) was pushing for some way to promote the usage of these more structured (note: I'd love a better term for HAL, SIREN, Cj, etc.) media types. Mike Amundsen (@mamund) suggested that putting community effort behind a single "winner" might not be appropriate, since that one might not be the right answer for everyone (or even the right answer for anyone).

We left with the idea of people "living with" a particular media type for 30-days and then provide feedback to the community (and library providers, if you used one). Since I (Ted Young) have already been "living with" Cj, and using a specific Java library, I'll be providing feedback on that, and will try living with HAL so that I can compare and contrast the experience.

If you are also going to give a media type a good solid try, please comment below.