For my research into REST I wanted to dive a little deeper into media types, but others have already done so years ago. It's great to read old blog posts and see they're still relevant today. So credit where credit is due, these are must-read posts about media types:
- RESTful resources are not typed (original/archive)
- The role of media types in RESTful web services (original/archive)
- hypermedia affordances (original/archive)
My findings (in random order)
- (Domain specific) media types further reduce the coupling between client and server. Instead of defining DTOs, a company should focus on defining domain specific media types that can be shared across its APIs. If competitors are willing to collaborate, domain specific media types can even be shared across an industry.
- Resources shouldn't be typed, but media types can be typed to make generation and parsing of requests and responses easier. With typing here I mean creating a class or interface that describes the data and options of the media type.
- A REST API has fewer endpoints than a JSON HTTP API, but the endpoints are more flexible; they support multiple media types.
- One media type can be supported by multiple resources (endpoints). For example: image/jpeg to get the picture of a person or a company logo.
- Just as the typing of a media type can be shared, so can validation across implementations be shared.