Integrating with other APIs poses an obvious concern. Even if called, this API alone would have no way of knowing whether any action of uploading is ever started, finished, failed nor aborted.
But the implementing backend, which has state can do two things when called:
save a notice of the upload, as if reserving a "slot"
expect that sometime, an update on the state of the upload is made
Then, it will need to just be notified when the latter happens and the process will be complete (regardless of success).
Designing that is simple enough.
Suggested resources
POST /upload_request - Should allocate a pointer for a future resource to be uploaded, and the user should be greeted with details to proceed to said upload.
PUT /upload_request -Should send the state of the resulting resource: the URL if successful, or metadata regarding error(s) or abortion of the process.
With the above in mind, a single object schema can be created with the following metadata to support the whole solution:
filename - Complete name of the file to be uploaded, extension included
extension - The extension of the file (after the dot e.g. png)
mimeType - MIME type of the file to be uploaded
uploadUrl - URL that the external service allowed to upload the file to
requestMethod - Accepted method for forwarding an upload request to that URL (probably POST)
requestPayloadType - Accepted option for forwarding an upload request to that URL (form data, JSON, others?)
tokenInclusion - Place where the token must be included (request body or header)
tokenName - Name of the key to the secret needed to use the upload URL
tokenValue - Value of the secret needed to use the upload URL
publicUrl - The resulting URL to view the file after upload is done
state - A one-word description of the state of the upload
Additional considerations
Both API calls above should only use objects with above metadata as request/response body.
The "external service" may not be just Dropbox, so it should be explicitly stated which one to use.
This comes from an issue to integrate storage services in the backend repository, but more specifically, Dropbox.
Integrating with other APIs poses an obvious concern. Even if called, this API alone would have no way of knowing whether any action of uploading is ever started, finished, failed nor aborted.
But the implementing backend, which has state can do two things when called:
Then, it will need to just be notified when the latter happens and the process will be complete (regardless of success).
Designing that is simple enough.
Suggested resources
POST /upload_request- Should allocate a pointer for a future resource to be uploaded, and the user should be greeted with details to proceed to said upload.PUT /upload_request-Should send the state of the resulting resource: the URL if successful, or metadata regarding error(s) or abortion of the process.With the above in mind, a single object schema can be created with the following metadata to support the whole solution:
filename- Complete name of the file to be uploaded, extension includedextension- The extension of the file (after the dot e.g.png)mimeType- MIME type of the file to be uploadeduploadUrl- URL that the external service allowed to upload the file torequestMethod- Accepted method for forwarding an upload request to that URL (probably POST)requestPayloadType- Accepted option for forwarding an upload request to that URL (form data, JSON, others?)tokenInclusion- Place where the token must be included (request body or header)tokenName- Name of the key to the secret needed to use the upload URLtokenValue- Value of the secret needed to use the upload URLpublicUrl- The resulting URL to view the file after upload is donestate- A one-word description of the state of the uploadAdditional considerations