REST Api: How to "create" a resource without the resource itself

See more:

REST

API

Hi codeproject,

i am currently designing a REST api as an alternative to a rather large soap based webservice (via asp.net mvc 3, although the technology is not really important).

While i am understanding the "ST" in REST as well as HATEOAS, i'm unfortunately struggling with a (probably) very basic problem:

Let's say that i have identified the following resources:

- A resource called "puzzle"
- A resource called "template"

I would run a HTTP GET on https://mydomain/myapi/puzzles/3 to retrieve puzzle 3.
I would run a HTTP POST on https://mydomain/myapi/puzzles/ to create a puzzle. In the body of my request, i would include my new "puzzle" resource with all required details. Maybe in json, maybe xml. whatever.

Now that is all very obvious, i would use the correct status codes, include hyperlinks and location headers for new resources and so forth.

But then, in addition to just post a new puzzle with all its details, it is possible to create a puzzle just by using a template id (id of a template resource, which defines one way of how a puzzle could look like).

In a RPC world, i would create two methods:

https://mydomain/myapi/CreatePuzzle (posting a puzzle)
https://mydomain/myapi/CreatePuzzlebyTemplateId (posting a templateid)

Both calls would return a valid new puzzle.

But how do i design that in a rest world? What is my naming convention? How am i supposed to build my url and resources?

Maybe i can concrete my question: How does a client "generate and retrieve" a new resource (my puzzle) by just posting a template id and not the new resource itself in a REST world?

I know how to just "solve the problem dirty", but how is it done right?

I really hope my question is clear, as it was difficult for me to phrase it. I also googled with bing and read more than one blog post and article.

Thank you guys for helping me out here.

Michael