This document discusses media types in RESTful applications. It defines what a media type is, including that it has a name, family of compatible schemas, hypermedia semantics, and processing rules. It discusses how to design a media type, including defining extensible schemas and avoiding mandatory elements. It also explains how media types enable evolvability by limiting contract changes to adding or removing data and controls while clients can ignore unknown elements. This allows services, clients, and contracts to evolve independently through loose coupling.

1. Understanding the Role
of Media Types in
RESTful Applications
Jan Algermissen / @algermissen
GOTO Copenhagen 2011

2. Application

3. Application
User

4. Application Use Case

5. Application
Application

6. Monolithic

7. User
Monolithic

8. Monolithic
Use Case

9. Monolithic
Application

10. Monolithic
Components

11. Monolithic
Connectors

12. Unix Command Line

13. User Unix Command Line

14. Unix Command Line Use Case

15. Unix Command Line
Application

16. Unix Command Line
Components

17. Unix Command Line
Connectors

18. Network-Based (ODBC)

19. User
Network-Based (ODBC)

20. Network-Based (ODBC)Use Case

21. Network-Based (ODBC)
Application

22. Network-Based (ODBC)
Components

23. Network-Based (ODBC)
Connector

24. Network-Based (ODBC)

25. Network-Based (ODBC)
User

26. Network-Based (ODBC)
Use Case

27. Network-Based (ODBC)
Application

28. Network-Based (ODBC)
Components

29. Network-Based (ODBC)
Connector

30. Network-Based (HTTP)

31. User Network-Based (HTTP)

32. Network-Based (HTTP)
Use Case

33. Network-Based (HTTP)
Application

34. Network-Based (HTTP)
User Agent Component
Intermediary Component Server Component

35. Network-Based (HTTP)
Connectors

36. Network-Based (HTTP)

37. User
Network-Based (HTTP)

38. Network-Based (HTTP)
Use Case

39. Network-Based (HTTP)
Application

40. Network-Based (HTTP)
User Agent Component
Intermediary Component Server Component

41. Network-Based (HTTP)
Connectors

42. Network-Based (HTTP)
Administrative Domain

44. Issues of
network-based,
decentralized
systems

45. Network
Issues of
network-based,
decentralized
systems

46. Network
Unpredictable
Use
Issues of
network-based,
decentralized
systems

47. Network
Unpredictable
Use
Issues of
network-based,
decentralized
systems
Complexity

48. Network
Unpredictable
Use
Issues of
network-based,
decentralized
systems
Trust Complexity

49. Network
Federated Unpredictable
Change Use
Issues of
network-based,
decentralized
systems
Trust Complexity

50. Performance
Network
Federated Unpredictable
Change Use
Issues of
network-based,
decentralized
systems
Trust Complexity

51. Performance
Network
Scalability
Federated Unpredictable
Change Use
Issues of
network-based,
decentralized
systems
Trust Complexity

52. Performance
Network
Scalability
Federated Unpredictable
Change Use
Issues of
network-based,
decentralized
systems
Trust Complexity
Simplicity

53. Performance
Network
Scalability
Federated Unpredictable
Change Use
Issues of
network-based,
decentralized
systems
Trust Complexity
Visibility Simplicity

54. Performance
Network
Evolvability Scalability
Federated Unpredictable
Change Use
Issues of
network-based,
decentralized
systems
Trust Complexity
Visibility Simplicity

55. Performance
Scalability
Simplicity
Visibility
Evolvability

56. Properties of Key Interest
Performance
Scalability
Simplicity
Visibility
Evolvability

57. Evolvability

58. GOAL
Server owner can implement any change
without asking existing clients.

59. Client Contract
Server

60. Contract
Client Server

61. Contract Media Type
Client Server

62. Media Type

63. Media Type
1.What is a media type?

64. Media Type
1.What is a media type?
2.How do I design one?

65. Media Type
1.What is a media type?
2.How do I design one?
3.How do media types enable evolvability?

66. 1. What is a media type?

67. 1. What is a media type?
•A name (identifier)

68. 1. What is a media type?
•A name (identifier)
•A family of compatible schemas

69. 1. What is a media type?
•A name (identifier)
•A family of compatible schemas
•Hypermedia semantics

70. 1. What is a media type?
•A name (identifier)
•A family of compatible schemas
•Hypermedia semantics
•Processing rules

71. 1. What is a media type?
•A name (identifier)
•A family of compatible schemas
•Hypermedia semantics
•Processing rules
•Extension rules

72. 2. How do I design a
media type?

73. Automatically check
prices and place order if
price is below threshold
User
Shop A
User Agent
(Crawler)
Shop B

74. UC 01: Automatically check prices and...
Primary Actor: User (Buyer)
Precondition: Crawler knows catalog entry URIs
Main Success Scenario:
1. User starts crawler
2. Crawler requests catalogs of known shops
3. Crawler compares prices of items to threshold
4. Crawler selects item if price below threshold
5. Crawler creates order for item
6. Crawler submits order to order-processor
7. Crawler archives order response
8. User reviews archived order responses

75. UC 01: Automatically check prices and...
Primary Actor: User (Buyer)
Precondition: Crawler knows catalog entry URIs
Main Success Scenario:
1. User starts crawler
2. Crawler requests catalogs of known shops
3. Crawler compares prices of items to threshold
4. Crawler selects item if price below threshold
5. Crawler creates order for item
6. Crawler submits order to order-processor
7. Crawler archives order response
8. User reviews archived order responses

76. Elements of Example
Media Type
Data:
Catalog (with items)
Order (with order-items)
Order Response
Hypermedia controls:
Order-Processor
(Catalog)

77. Catalog Example
<catalog>
<title>Shoe Catalog</title>
<order-processor href="/orders"/>
<item id=”123” href=”/items/23”>
<name>Shiny Boots</name>
<price currency="EUR" amount="27.99">
</item>
<item id=”456” href=”/items/388”>
<name>Fancy Sneakers</name>
<price currency="EUR" amount="12.95">
</item>
</catalog>

78. Order Example
<order>
<buyer>...</buyer>
<line-items>
<line-item id=”123”>
<price currency=”EUR”>27.99</price>
<quantity>4</quantity>
</line-item>
<line-item id=”456”>
<price currency=”EUR”>12.95</price>
<quantity>4</quantity>
</line-item>
</line-items>
</order>

79. application/procurement
•Three schemas <catalog>, <order> and
<order-response>
•No mandatory elements
•Extensible
•Specified as version 1
•Processing Rules
If an <order-processor> element is present an order can be POSTed to that resource.
Such an oder accepting resource SHOULD accept <order>-documents.
...

80. 3.How does a media type
enable evolvability?

81. 3.How does a media type
enable evolvability?
Contract Media Type
Client Server

82. Shop Service
@GET
@Produces("application/procurement")
public String makeProcurementCatalog() {
return "<catalog/>";
}

83. Catalog Example
<catalog>
<title>Shoe Catalog</title>
<order-processor href="/orders"/>
<item id=”123” href=”/items/23”>
<name>Shiny Boots</name>
<price currency="EUR" amount="27.99">
</item>
<item id=”456” href=”/items/388”>
<name>Fancy Sneakers</name>
<price currency="EUR" amount="12.95">
</item>
</catalog>

84. Shop Service (improved)
@GET
@Produces("application/procurement")
public Catalog makeProcurementCatalog() {
Catalog catalog = new Catalog(“Shoe Catalog”);
catalog.setOrderProcessor("/orders");
catalog.addItem("/items/23","Shiny Boots","27.99");
catalog.addItem("/items/388","Fancy Sneakers","12.95");
return catalog;
}

85. Server Development Principle
Design by purpose

86. Crawler Implementation
public void handleCatalog(catalogUri) {
WebResource resource =
getClient().resource(catalogUri);
ClientResponse response =
resource.get(ClientResponse.class);
Catalog catalog = response.getEntity(Catalog.class);
Item item = catalog.getItemById(“123”);
if(item != null && item.getPrice() != null
&& item.getPrice().getAmount(“EUR”) < THRESHOLD) {
placeOrder(catalog,item);
}
}

87. Crawler Impl. (cont.)
public void placeOrder(Catalog catalog, Item item) {
String orderProcessorUri = catalog.getOrderProcessorUri();
Order order = new Order(item);
WebResource resource =
getClient().resource(orderProcessorUri);
ClientResponse response =
resource.post(ClientResponse.class,order);
// handle order placement response
}

88. Client Development Principle
Design by intent

89. Observation
REST limits the possible contract
changes to just two kinds: Adding
data or controls and removing data or
controls from a message.

90. New Requirement
Add in-stock quantity

91. Extended Catalog Example
GET /catalog
200 Ok
Content-Type: application/procurement
<catalog>
<title>Shoe Catalog</title>
<order-processor href="/orders"/>
<item id=”123” href=”/items/23”>
<name>Shiny Boots</name>
<price currency="EUR" amount="27.99">
<in-stock>5</in-stock>
</item>
<item id=”456” href=”/items/388”>
<name>Fancy Sneakers</name>
<price currency="EUR" amount="12.95">
<in-stock>2</in-stock>
</item>
</catalog>

92. Media Type Principle
Extensible schemas

93. Client Development Principle
“Must Ignore”

94. Share Useful Extensions
Feed extensions back into
media type, increase schema
version.

95. Shop Server Change
No order processor available

96. Catalog Example
GET /catalog
200 Ok
Content-Type: application/procurement
<catalog>
<title>Shoe Catalog</title>
<item id=”123” href=”/items/23”>
<name>Shiny Boots</name>
<price currency="EUR" amount="27.99">
</item>
<item id=”456” href=”/items/388”>
<name>Fancy Sneakers</name>
<price currency="EUR" amount="12.95">
</item>
</catalog>

97. Crawler Impl. (fails)
public void placeOrder(Catalog catalog, Item item) {
String orderProcessorUri = catalog.getOrderProcessorUri();
Order order = new Order(item);
WebResource resource =
getClient().resource(orderProcessorUri);
ClientResponse response =
resource.post(ClientResponse.class,order);
// handle order placement response
}

98. Crawler Impl. (improved)
public void placeOrder(Client Response response,
Catalog catalog, Item item) {
String orderProcessorUri = catalog.getOrderProcessorUri();
if(orderProcessorUri == null) {
throw new FailedExpectationException(
“Expected order processor not found”,response);
}
Order order = new Order(item);
WebResource resource =
getClient().resource(orderProcessorUri);
ClientResponse response =
resource.post(ClientResponse.class,order);
// handle order placement response
}

99. Crawler Impl. (improved)
try {
handleCatalog(catalogUri);
} catch(FailedExpectationException e) {
String message = e.getMessage();
ClientResponse response = e.getClientResponse();
LOG.error( ... );
reportIncident(
“Failed expectation when processing catalog ” +
catalogUri,
message, response, PRIORITY_CRITICAL);
// ...
}

100. Client Development Principle
“What if” programming style

101. Media Type Principle
Avoid mandatory elements

102. Server Development Principle
Be responsible

103. If you are a media type
designer...

104. If you are a media type
designer...
•Define extensible schemas

105. If you are a media type
designer...
•Define extensible schemas
•Avoid mandatory elements

106. If you are a server
developer...

107. If you are a server
developer...
•Use from the media type what suits your
possibilities

108. If you are a server
developer...
•Use from the media type what suits your
possibilities
•Be responsible and maintain things

109. If you are a client developer...

110. If you are a client developer...
•Use from the media type what suits your
intended application

111. If you are a client developer...
•Use from the media type what suits your
intended application
•Ignore unknown data and controls

112. If you are a client developer...
•Use from the media type what suits your
intended application
•Ignore unknown data and controls
•“What if” programming style

113. Server does not own
the contract

114. Flexible Contract

115. Source of information

116. Q&A