API MBO signoff checklist
This issue is more to formalize the requirements for signoff and to provide a list of the features and the expected flow of the application to aid in testing.
Feature requirements
- #5 (closed) - CRUD endpoints
- #6 (closed) - Callbacks from Dropbox Sign (Hellosign)
- #7 (closed) - Binds to original data structure
- #8 (closed) - Configurable templates
- #10 (closed) - Requires authentication
Of these features, there is only a partial success/failure for #5 (closed), as we only have basic read and create operations. The update and delete present some technical problems and complications that are somewhat outside the scope of this initial work. I could look to start implementing those last 2 endpoints, but as they were not in the initial API either, I think its safe to push them to the next quarter at least.
With regards to authentication, all endpoints are secured in a way that makes unauthorized calls next to impossible. All of the data access points for our persisted data is guarded by Keycloak authentication, which will use a similar access pattern as other service account-protected endpoints like the FoundationDB API. The Hellosign API callback endpoint uses a call provided by the Hellosign client that calculates a hash from the API key that should rebuff any requests that aren't authentic.
A note to be had is that there will be some minor changes to the configuration to enable legacy data binding, as the template table has been dropped as it isn't needed for typical access and can easily be set as configuration since none of the data is sensitive. This work hasn't been done yet, but it should be a simple matter to add support for it once we start looking at integrating the API.
Endpoints in the API
Below are the endpoints that exist in the API with their current real endpoints, as they deviate slightly from the API spec. More details on return bodies and other notes can be seen in the spec under ./spec/openapi.yaml.
| Method | URL | Description |
|---|---|---|
| GET | https://api-staging.eclipse.org/sandbox/foundation/hellosign | Get all current requests |
| POST | https://api-staging.eclipse.org/sandbox/foundation/hellosign | Create a new request |
| GET | https://api-staging.eclipse.org/sandbox/foundation/hellosign/{id} | Get a specific request |
| GET | https://api-staging.eclipse.org/sandbox/foundation/hellosign/{id}/document | Get the current document for the given request if it exists |
| POST | https://api-staging.eclipse.org/sandbox/foundation/hellosign/callback | Hellosign API webhook callback endpoint, not to be used manually |
For the authentication, you can ask me for the credentials to a test client in the configured test realm for access and I can provide it. You should be able to configure it as a client_credentials OAuth2 authentication type with an access token URL of https://auth.eclipse.org/auth/realms/document-signature-staging/protocol/openid-connect/token. This can be in Insomnia, and should also be possible in Postman if that is the REST client you use.
Expected usage scenarios
- Usage of the GET endpoints to manage and read the state of various signature requests, as well as retrieving the document as a data stream for download.
- Creating new requests via the standard POST endpoint, allows for a single 'client' that will represent the user that should sign the request. This will create a request entry in the database, track all of the signers in the signers table, and fire a request to hellosign to create the request.
- If a bad template ID is passed, then the request is rejected
- Currently, this allows users without Eclipse accounts to be set as a signer, though the completion of the workflow will fail if the user does not exist. (I will work on adding that validation)
- Incoming updates from Hellosign to the callback API will be validated and actioned according to the type of event that was actioned upstream. These will be tracked in the database via the signature event table.