zkong-gsma
commented
3 years ago The Current "design" is based upon below.
for eg.
from https://www.lawdepot.com/contracts/service-contract/ as an example.
like a paper contract, we have "pre-defined" Signature Object (greenbox)
each Box is represented by its own "signatureId"
/contracts/{contractId}/signatures/{signatureId}
A PUT method is use to "Add" a Signature to the "box".
On the other hand,
IF a POST method is preferred, it would reflect to something such as
where we have an "empty" space where someone will then Have to Add a whole "Signature" Object. and technically allowing/requiring the "submitter" to add "additional" information such as "fromMSP/toMSP" (although this is restrict/automated by default), the "Role" etc.
So, as much as the concern is that a "signature" could be overwritten when using a "PUT" method, (it will throw an error when someone is trying to override the object), Similarly a "POST" method gives an Assumption that one can Add multiple extra "signatures" to the Document. (again can be handled by throwing an error to say Max required signature obtained)
Hence from a logical thinking perspective that in the future, when it comes to properly defining a "signature" process. (when we do it properly), Some form of "pre-determine" person that is expected to sign the contract will logically be required. Eg, a Approver "List" from each Org, that we can "select". or some Role Matching. etc etc.
And it is more appropriate to use the "PUT" (predetermine) method, as we would have pre-define, who's signature is required for the contract. and only them can provide the signature.
The current API permits adding new signatures via the route
PUT /contracts/{contractId}/signatures/{signatureId}. That is because empty signatures are created internally when creating the contract object. Therefore, these empty slots would be updated with a new signature. However, this may be confusing to users of the API, as it may seem like signatures could be overwritten. Therefore, I would like to propose to update the API so that it becomes apparent, that only new signatures can be added to contracts and old signatures cannot be overwritten:Using POST indicates that a new signature is added. Furthermore, no signatureId is required, as such mapping should be handled internally, if required at all.