RFC: API enhancements
Currently, the provided API for this service allows the conversion of a single .docx
file into an HTML
format.
The task at hand is to enhance the existing API in order to facilitate first the split of a single .docx
file into multiple parts and then convert each part into HTML
format.
A new endpoint should be created for this purpose.
POST
/api/convertAndSplit
or /api/splitAndConvert
depending on the actual sequence of things.
This endpoint will have its own controller. As we are talking about an async operation the required parameters of that endpoint (included in the body of the request) will be:
Body part of the request
-
docx
will have the actual file -
serviceCredentialId
an id which will represent thismicroservice
on the caller side (will be used in the async response) -
responseToken
a generated token (on the caller side) which will be used when this service provide a response back to the caller (will be used in the async response) -
serviceCallbackTokenId
an id which will map the aforementionedresponseToken
to the specific service call on the caller side (will be used in the async response) -
callbackURL
theURL
of the server who called the service
All the above will be provided by the caller of the service (e.g Editoria) and the majority of them (serviceCredentialId
,responseToken
,serviceCallbackTokenId
,callbackURL
) will be passed through to the async job of splitting and converting.
The synchronous response of the endpoint should be a json
object with the attribute of msg
and either:
- status code 200 and
{msg:'ok'}
for the case where everything is good - status code 500 and
{msg:some_error_message}
for the case where an error occurred
similar to this https://gitlab.coko.foundation/cokoapps/xsweet/-/blob/master/server/api/xsweet.controller.js#L33
The controller of the endpoint should post a job to the job queue of the microservice which will be responsible to actually execute the chain of corresponding conversion and spitting scripts at a later time. The outcome of the execution of these scripts should be an array of strings. Each item will be the HTML
content of a chapter e.g.
['<html>
<body>
.
.
.
</body>
</html>', '<html>
<body>
.
.
.
</body>
</html>',...]
This array of strings will be used as a payload when the posted job will call back the service's caller and provide the converted chapters using the following params serviceCredentialId
,responseToken
,serviceCallbackTokenId
,callbackURL