uri - REST convention for parent insert and parent + joinId insert using same endpoint -

in context of event management system speakers talking @ different sessions. entities speakers , sessions

let's endpoint

1) post /speakers (to insert detail of speaker only)

2) post /speakers (to insert detail of speaker + id of session he's talking on)

point 2 requires additional insert in join table.

how can specify both kinds of operations within same endpoint.

a speaker represented including session speaks on. example:

{   "id": 1234,   "firstname": "joe",   "lastname": "doe",   "sessions": [] } 

this representation means speaker is not speaking on session. sessions empty array. doing

post /speakers content-type: application/json 

with json body show above, create speaker.

if client knows in advance sessions speaker speaking, json this:

{   "id": 1234,   "firstname": "joe",   "lastname": "doe",   "sessions": [     {       "id": 12,       "link": "/session/12"     },     {       "id": 34,       "link"; "/session/34"     }   ] } 

for each session speaker speaking on, short object consisting of id , link session included. should enough server know how link speaker , sessions in database.

now let's consider case, sessions speaker speak on not known in advance client. client create speaker using first json representation above including empty sessions array. later, when sessions speaker speak on known client, make patch request:

patch /speakers/1234 content-type: application/json  {   "sessions": [     {       "id": 12,       "link": "/session/12"     },     {       "id": 34,       "link"; "/session/34"     }   ] } 

note send sessions. other attributes of speaker shall left on server.

if client wants add sessions speaker 1 after other, every session:

post /speakers/1234/sessions content-type: application/json  {   "id": 43,   "link": "/sessions/43" } 

this mean: "add session 43 list of sessions of speaker 1234". here /speakers/1234/sessions sub resource of /speaker/1234. adding makes sense (of course server have check duplicates).

note different usage of post create new resource (a speaker), add sub resource (the list of sessions). note changing part of resource (the speaker) uses patch.

edit:

the http verb put used if client wants send complete representation of resource. when adding list of sessions existing speaker, use patch on speaker because using put on him require client send a complete representation of speaker. in use case client not want this, wants set list of sessions.

an alternative way to

put /speakers/1234/sessions content-type: application/json  [   {     "id": 12,     "link": "/session/12"   },   {     "id": 34,     "link"; "/session/34"   } ] 

with complete list of sessions on subresource sessions. note difference: here client sending complete representation of list of sessions speaker. here put means: "overwrite complete list of sessions speaker provide".

using /speakers?eventid=1 list of speakers 1 practice. here client requests filtered subset of collection resource /speakers. using query parameter express filter conditions common.

about resources kind of knowledge general advice think resource. resources api provides? how different types of resources related? can exist next each other (a speaker can exist without session, session can exist without speaker), or composites (a hotel room can exist inside hotel). kind of question helps. in rest there no hard rules or "standards" how urls must constructed. think important consistent in api.