RESTful Web Services Cookbook

Chapter 3. Designing Representations

As far as clients are concerned, a resource is an abstract entity that is identified by a URI. A representation, on the other hand, is concrete and real since that is what you program to and operate upon in clients and servers.

Recall from Recipe 1.1 that HTTP provides an envelope format for representations in requests and responses. Designing a representation involves (a) using that envelope format to include the right headers, and (b) when there is a body for the representation, choosing a media type and designing a format for the body. This chapter presents the following recipes covering various aspects of representation design:

Recipe 3.1

Use this to decide what entity headers to include when sending a representation.

Recipe 3.2

Use this to decide how to interpret entity headers from a representation received.

Recipe 3.3

Use this recipe to learn about some precautions about character encoding mismatch.

Recipe 3.4

Use this recipe to find the criteria to choose a representation format and a media type.

Recipe 3.5

Use this recipe to decide the essential ingredients for XML-formatted representations.

Recipe 3.6

Use this recipe to learn how to design JSON-formatted representations.

Recipe 3.7

Refer to this recipe to learn about the conventions used to design representations of collections.

Recipe 3.8

Use this recipe to check for guidelines on how to keep collections easy to iterate.

Recipe 3.9

Use this recipe to learn about interoperable ways to format numbers, ...