POST parameters on REST api - links or inline? - rest

Question

I am trying to design a rest api and i have a resource with links to another resource. say
GET /resource1/id1
{
"property1": "value1",
...
"links" : [
{
"rel": "res1to2rel",
"href": "/resource2/r2"
}
]
now on a post to create resource1, i want to pass a relationship to resource2. should the POST call look like
POST /resource1
{
"res1to2rel": "/resource/r2"
}
or should it look like
POST /resource1
{
"links" : [
{
"rel": "res1to2rel",
"href": "/resource2/r2"
}
]
}
What is the best practice, should the POST match the GET or can it have properties that you dont see on GET?

Answer 1

There're few absolute rules when it comes to REST design, but I think that it'd be easier for the client if a resource has a consistent set of representations. When you POST a representation, you typically create a new resource. This can be made even more explicit by:
Returning 201 Created.
Returning a Location header in the response.
Returning a copy of the representation as the server sees it.
Thus, a POST might look like this:
POST /resource1 HTTP/1.1
Content-Type: application/json
{
"property1": "value1",
...
"links" : [
{
"rel": "res1to2rel",
"href": "/resource2/r2"
}
]
}
The response might then be:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /resource1/id1
{
"property1": "value1",
...
"links" : [
{
"rel": "self",
"href": "/resource1/id1"
},
{
"rel": "res1to2rel",
"href": "/resource2/r2"
}
]
}
Notice that the server is allowed to enrich the resource, in the above example by adding a "self" link.
If a client later makes a GET request against the address supplied in that LOCATION header, it'll receive the same response as the echo it received from the POST request:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"property1": "value1",
...
"links" : [
{
"rel": "self",
"href": "/resource1/id1"
},
{
"rel": "res1to2rel",
"href": "/resource2/r2"
}
]
}
This makes it easier for clients to interact with the API because it can use the same internal model for reading and writing (i.e. serialising and deserialising) representations of a resource.