Action linking in REST that will create a resource based on a existing resource - rest

Question

I'm struggling to get action links into my resource to fulfill HATEOAS.
I would like to create a new resource based on an existing resource and still fulfill a sound hypermedia strategy. In my case, append an existing test request on a generic server side job queue.
My current flow (simplified for clarity) for doing this does not use hypermedia to link the action of actually queuing the test_request (creating a job resource on the jobs collection).
Create test_request resource
POST http://example.org/api/v1/test_request
{
'name': 'Some example tests',
'test': 'test1'
}
201, CREATED
{
'id': 3
'name': 'Some example tests',
'test': 'test1',
'links': [
{
'rel': 'self',
'href': 'http://example.org/api/v1/test_request/3',
'method': 'GET',
},
{
'rel': 'remove',
'href': 'http://example.org/api/v1/test_request/3',
'method': 'DELETE',
}]
}
Generate a job resource
POST http://example.org/api/v1/jobs
{
'type': 'test_request',
'id': 3
}
201, CREATED
{
'id': 12,
'type': 'test_request',
'status': 'new',
'links': [
{
'rel': 'self',
'href': 'http://example.org/api/v1/jobs/12',
'method': 'GET',
},
{
'rel': 'remove',
'href': 'http://example.org/api/v1/jobs/12',
'method': 'DELETE',
}]
}
To fulfill Hypermedia criteria on my REST API I'm really tempted to add an action link on the test_request resource so that a new job resource is created for the same.
Modified test_request representation
{
'id': 3
'name': 'Some example tests',
'test': 'test1',
'links': [
{
'rel': 'self',
'href': 'http://example.org/api/v1/test_request/3',
'method': 'GET',
},
{
'rel': 'remove',
'href': 'http://example.org/api/v1/test_request/3',
'method': 'DELETE',
},
{
'rel': 'http://example.org/rels/queue',
'href': 'http://example.org/api/v1/test_request/3/queue',
'method': 'PUT',
}]
}
So, the first examples are (hopefully) RESTful were my second approach with the queue action are maybe more unRESTful. However, it's really nice to have a link in the test_request representation that clearly states an action to make the next transition.
What's best practice here?

Answer 1

Your question isn't super clear, so i'm gonna go with my interpretation of what you're asking, maybe that can help get an answer.
The root question is a domain question that only you can really answer. Can and should a Test exist without being part of a job? You need to think through your use cases and make a decision. If a test is a weak entity, then you should only allow the creation through the jobs.
Regarding your strive for RESTful architecture. I would suggest eliminating the concept of the id field from your API. The self link is the ID. When you create the job you can provide the collection of links to the tests that you want to be included in the job. Something like
POST http://example.org/api/v1/jobs
{
'type': 'test_request',
'links': [
{
rel : "test",
href : "http://example.org/api/v1/test_request/3",
},
{
rel : "test",
href : "http://example.org/api/v1/test_request/4",
}
]
}
Note: i'm unsure how your hypertext format deals with multiple links for the same relationship...i made a guess.
It's my opinion that Primary Keys and Foreign Keys should never exist in a RESTful API. Links should always be used.