CODEWITHSUNDEEP
restasp.net-web-api
Jon Susiak
Jon Susiak

Reputation: 4978

Creating a resource that can have multiple representations

Say I have a Widget resource which is made up of a Thingy and a Dooda. Thingys and Doodas come in various types and the combination of Thingy type and Dooda type will determine exactly what properties a Widget will have. Whilst I understand that in order to create a Widget I should send a complete representation of the resource, the potential combination of Thingys and Doodas is numerous so it is impractical to send all the possible properties in one Widget object.

Therefore in order to create a Widget I only require those properties to be sent that are defined by the combination of Thingy and Dooda. What is the best way to communicate to the client the definition of the representation to send?

My first thoughts are to provide an endpoint to which the client can send the Thingy/Dooda type combination and receive back a blank 'template' representation of the Widget which defines which properties are required, or is there a better way to handle this situation?

Upvotes: 2

Views: 843

Answers (1)

Darrel Miller
Darrel Miller

Reputation: 142252

Here is one way

> GET http://acme.com/api

< 200 OK
< Content-type:  application/hal+xml

<resource>
   <!-- Home resource for acme API -->
   <link rel="create-form" href="http://acme.com/api/widgets/form{?thingyType,doodaType}"
</resource>

Hal is a standard hypermedia format defined here. The create-form link relation type is defined in RFC 6861. The URI is using the URI-template format defined in RFC 6570. The client must resolve the URI template and follow the rules of create-form to retrieve a form representation.

> GET /acme.com/api/widget?thingyType=foo&doodaType=bar

< 200 OK
< Content-Type:  application/xhtml

<html>
   <form method="POST"href="http://acme.com/api/widgets">
       <input type="text" name="thingyX">
       <input type="text" name="thingyY">
       <input type="text" name="doodaA">
       <input type="text" name="doodaB">
   </form>
</html>

In this example I have used a html form. However, there is no requirement to use this type of form. Some other form type media type could be used.

> POST http://acme.com/api/widgets
> Content-Type:  x-application/www-form-urlencoded

thingyX=20&thingyY=45&doodaA=yo&doodaB=dawg

< 201 Created
< Location: http://acme.com/api/widgets/975

Once the widget is created, it can be retrieved in any representation media type you like.

> GET  http://acme.com/api/widgets/975

< 200 OK
< Content-Type:  application/vnd.acme.widget+xml

<widget>
  <thingy X="20" Y="45">
  <dooda A="yo" B="dawg"/>
</widget>

Upvotes: 2

Related Questions