Cover by Subbu Allamaraju

Safari, the world’s most comprehensive technology and business learning platform.

Find the exact information you need to solve a problem on the fly, or go deeper to master the technologies and skills you need to succeed

Start Free Trial

No credit card required

O'Reilly logo

3.4. How to Choose a Representation Format and a Media Type

This may be one of the first questions to come to mind when designing a RESTful web service. However, no single format may be right for all kinds of resources and representations. Picking up a format like JSON or XML for all representations may reduce the flexibility that HTTP has to offer.

Problem

You want to know how to choose a format and a media type for representations.

Solution

Keep the choice of media types and formats flexible to allow for varying application use cases and client needs for each resource.

Determine whether there is a standard format and media type that matches your use cases. The best place to start your search is the Internet Assigned Numbers Authority (IANA, http://www.iana.org/assignments/media-types/) media type registry.

If there is no standard media type and format, use extensible formats such as XML (application/xml), Atom Syndication Format (application/atom+xml), or JSON (application/json).

Use image formats like image/png or rich document formats like application/vnd.ms-excel or application/pdf to provide alternative representations of data. When using such formats, consider adding a Content-Disposition header, as in Content-Disposition: attachment; filename=<status.xls> to give a hint of the filename that the client could use to save the representation to the filesystem.

Prefer to use well-known media types for representations. If you are designing a new media type, register the format and media ...

Find the exact information you need to solve a problem on the fly, or go deeper to master the technologies and skills you need to succeed

Start Free Trial

No credit card required