Make a RESTful API call that updates many related entities

Question

We have a model that looks like this

Login <- Email Addresses <- Person -> Teen

And a stored procedure which takes some properties from teen, some from person, and some from Login, and creates a new teen, returning a person entity.

Looking from a classic RPC perspective, this is easy...just expose a method InsertTeen and have it call the stored procedure.

I've been trying to wrap my head around the RESTful idea of having URLs as my resources (nouns), and the only actions being HTTP actions (verbs). Obviously, a URL like /api/InsertTeen is not RESTful at all.

But here I'm not dealing with any particular resource.

The only thing I can thing of here would be to expose a resource like insertTeenRequest.

Are there any other ideas of how to do this? Am I being too much of a "zealot"?

Answer 1

Pretty new to REST myself, but my thinking is that here you would use a "POST" with the body of the request containing the data needed to create a 'Teen', in whatever format you are using, usually JSON or XML. Here, I'm not sure whether you treat Teens as Persons with additional properties, or a Teen is modeled as an entity itself:

<person login="abc" email="abc@foo.com">
   <person-property-1>value1</person-property-1>
   <person-property-2>value2</person-property-2>
   <teen>
      <teen-property-1>value3</teen-property-1>
      <teen-property-2>value4</teen-property-2>
   </teen>
</person>

or

<teen login="abc" email="abc@foo.com">
   <person-property-1>value1</person-property-1>
   <person-property-2>value2</person-property-2>
   <teen-property-1>value3</teen-property-1>
   <teen-property-2>value4</teen-property-2>
</teen>

Regarding the URI, I believe the segments should be nouns rather than verbs since the URI is supposed to address a resource, so /api/teens rather than /api/InsertTeen.

/api/teens with an HTTP GET would return a list of all Teens, and /api/teens with an HTTP POST would insert a new Teen. To round out the CRUD operations, /api/teens/{id} using HTTP GET would return a specific Teen, /api/teens/{id} with an HTTP PUT would update a Teen using the values passed in the request body, and /api/teens/{id} called with HTTP DELETE would delete the specified Teen.

Edit

Read over your question again, and I may have misunderstood. If you aren't treating 'teens' as a resource, but only 'people', then I would consider /api/people with an HTTP POST, and depending on the values passed in the body of the request, do whatever is appropriate to store that 'person'. So, if the request contained 'teen' values, call your stored procedure that creates a 'Teen' and returns a 'Person'.

HTH

Answer 2

If you want to be really RESTful, you should use several requests to your API in this case. For example first you create Teen with POST to /api/teens/, then create Person with POST to /api/persons/ and so on.