Reorganize API endpoints and deprecate current endpoints

[Chartman123]

Based on the comment by @susnux, here's the proposal on how to reorganize our API endpoints:

Forms endpoints

What	Current	New
Get forms	GET /forms	✅ GET /forms[?type=owned]
Get shared forms	GET /shared_forms	✅ GET /forms?type=shared
New form	POST /form	✅ POST /forms
Get form	GET /form/:id:	✅ GET /forms/:form-id:
Get partial form	GET /partial_form/:hash:	❓ GET /forms/0?hash=:form-hash:
Clone form	POST /form/clone/:id:	✅ POST /forms?fromId=:form-id:
Update form	PATCH /form/update	✅ PATCH /forms/:form-id:
Transfer ownership	POST /form/transfer	✅ - (just use patch/update)
Delete form	DELETE /form/:id:	✅ DELETE /forms/:form-id:
Link file to form	POST /form/link/:fileformat:	✅ - (just use patch/update)
Unlink file	POST /form/unlink	✅ - (just use patch/update)

Questions endpoints

What	Current	New
Get questions	-	✅ GET /forms/:form-id:/questions
Get question	-	✅ GET /forms/:form-id:/questions/:question-id:
New question	POST /question	✅ POST /forms/:form-id:/questions
Update question	PATCH /question	✅ PATCH /forms/:form-id:/questions/:question-id:
Reorder questions	PUT /question/reorder	✅ PUT /forms/:form-id:/questions/reorder
Clone question	POST /question/clone/:id:	❓ POST /forms/:form-id:/questions/:question-id:/clone
Delete question	DELETE /question/:id:	✅ DELETE /forms/:form-id:/questions/:question-id:

Options endpoints

What	Current	New
Get options	-	✅ GET /forms/:form-id:/questions/:question-id:/options
Get option	-	✅ GET /forms/:form-id:/questions/:question-id:/options/:option-id:
New option(s)	POST /option	✅ POST /forms/:form-id:/questions/:question-id:/options
Update option	PATCH /option/update	✅ PATCH /forms/:form-id:/questions/:question-id:/options/:option-id:
Reorder options	-	✅ PUT /forms/:form-id:/questions/:question-id:/options/reorder
Clone option	-	❓ POST /forms/:form-id:/questions/:question-id:/options/:option-id:/clone
Delete option	DELETE /option/:id:	✅ DELETE /forms/:form-id:/questions/:question-id:/options/:option-id:

Sharing endpoints

What	Current	New
Get user's shares	-	✅ GET /shares
Get shares of a form	-	✅ GET /forms/:form-id:/shares
Get share	-	✅ GET /forms/:form-id:/shares/:share-id:
New share	POST /share	✅ POST /forms/:form-id:/shares
Update share	PATCH /share/update	✅ PATCH /forms/:form-id:/shares/:share-id:
Delete share	DELETE /share/:id:	✅ DELETE /forms/:form-id:/shares/:id:

Submission endpoints

What	Current	New
Get submissions	GET `/submissions/:formhash:	✅ GET /forms/:form-id:/submissions
Get submission	-	✅ GET /forms/:form-id:/submissions/:submission-id:
Download submissions	GET /submissions/export/:formhash:?:fileformat:	✅ GET /forms/:form-id:/submissions -> Parameters download, filetype
Export submissions to cloud	POST /submissions/export	✅ POST /forms/:form-id:/submissions-> Parameters fileformat, path
New submission	POST /submission/insert	✅ POST /forms/:form-id:/submissions
Update submission	-	✅ PATCH /forms/:form-id:/submissions/:id:
Delete submissions	DELETE /submissions/:formid:	✅ DELETE /forms/:form-id:/submissions
Delete submission	DELETE `/submission/:id:	✅ DELETE /forms/:form-id:/submissions/:submission-id:

[susnux]

❓ GET /forms/:id: -> Parameter: partial = true

I do not think we need this, either we have permissions on that form -> get all information, or we do not have (e.g. just shared for submit) -> get only partial

[susnux]

✅ POST /forms/:id:/clone

Or maybe same as creating a new and POST /forms and content: { id: 1234567 }. I searched for similar APIs, sometimes it is also something like POST /forms?fromId=1234.

[susnux]

But more important: Do we want logical nesting? E.g.:

• POST /forms/{form-id}/questions vs POST /questions
• DELETE /forms/{form-id}/questions/{question-id} vs POST /questions/{question-id}

I personally think it makes sense for forms, as we always need to query the form to check access to question / option etc.

But I am not sure about shares, because they are also bound to forms, like:

• POST /forms/{form-id}/shares makes sense to create a new share for that form

But we also need /shares to fetch shares for the current user. EXCEPT if we include that in our /forms endpoint.

[Chartman123]

But I am not sure about shares, because they are also bound to forms, like:

* POST `/forms/{form-id}/shares` makes sense to create a new share for that form

But we also need /shares to fetch shares for the current user. EXCEPT if we include that in our /forms endpoint.

What about having both? /shares for querying the user's shares and /forms/{form-id}/shares to manage the shares of a form?

[susnux]

What about having both? /shares for querying the user's shares and /forms/{form-id}/shares to manage the shares of a form?

Would work for me :)

[Chartman123]

I've updated the tables with the proposed new routes :)

[Chartman123]

Do we want to split our API requests and deliver only the forms when you query /forms and only get the /forms/:form-id:/questions when you do another query? We could deliver the URI for the questions in the forms response then... But this would of course be a bigger change then...