...
The addition of the new field: termsOfServiceVersion
is a backwards compatible change. If an old client calls this service without providing this new field, a default value of ‘0.0.0’ will be used to indicate that the user has agreed to the deprecated ToS. If the user attempts to set a version that is newer than the current version, an error will be returned.
We will also update the LoginResponse object returned by: POST /login2 API response to include the more information the user’s ToS status:
LoginResponse.json
...
language | json |
---|
...
. The UI can use this information to show a message to the user when they need to agree to new ToS.
New ToS APIs
The following will be the new ToS APIs. These new services will be added under the “Authentication Services”
Response | URL | Request | Description | Authorization |
---|---|---|---|---|
TermsOfServiceInfo | GET /termsOfUse2/info | none | Get information about the current ToS | Not Required |
TermsOfServiceInfo | PUT /termsOfUse2/requirements | TermsOfServiceRequirement | Sets the global ToS requirements. | Only ACT or Admin may make this call. |
TermsOfServiceStatus | GET /termsOfUse2/status | none | Get the current user’s ToS status. Used to determine if the user needs to agree to the new ToS | This call needs to work with a standard auth token in the header to identify the user but the caller does know the ID of the user yet. |
Note: The starting TermsOfServiceRequirement will be set with minimumTermsOfServiceVersion=0.0.0
and requirementDate=1/1/2011
. All existing users that have agreed to the exiting ToS will meet the starting requirements. This means ACT will need to set the new requirements before users will be required.
Storage Limit APIs
We will use the following pseudo-query to determine the total number of bytes for each storage location and project combination:
Code Block |
---|
SELECT PROJECT_ID, STORAGE_LOCATION_ID, SUM(FILE_SIZE_BYTES) FROM OBJECT_REPLICATION GROUP BY PROJECT_ID, STORAGE_LOCATION_ID; |
Since this query can read millions of rows per project, we will cache (all containers for moves) the results for quick retrieval.
Note: While the following API will work for all combination, clients can “hard-code” the default Synapse storage location ID. The new API will be added under the “Project Setting Services”.
Response | URL | Request | Description | Authorization |
---|---|---|---|---|
ProjectStorageUsage | GET /project/{projectId}/storage/usage | none | Get the information about all combinations for a single project. | The UserEntityPermissions.hasUpload=true for the project. “Plan managers” will have access to this. |
ProjectStorageLocationLimit | POST /project/{projectId}/storage/limit | ProjectStorageLocationLimit | Set the limit for a single combination | Only members of the “plan managers” team may call this service. |
Checking Limits Before Upload
Before a client uploads a file to a project or folder, the client will first call GET /entity/{id}/uploadDestination. We will extend the resulting UploadDestionation object to include information about the containing project and its limits. This will allow clients to block the upload of a file that would be over the limit using the following pseudo-code:
Code Block |
---|
if (sumFileBytes + newFileSize > maxAllowedFileBytes) then block upload |
Since we are changing the UploadDestionation object, GET /entity/{id}/uploadDestination/{storageLocationId} service will also return the new project limit information.
Model Objects
TermsOfServiceInfo.json:
Code Block | ||
---|---|---|
| ||
{ "description": "Information about the current Synapse Terms of Service (ToS).", "properties": { "termsOfServiceUrl": { "type": "string", "description": "The URL that can be used to fetch the latest ToS using an HTTPS GET." }, "latestTermsOfServiceVersion": { "type": "string", "description": "The date/time whensemantic version of the userlatest lastToS agreedin tothe theprovided ToSURL. Will be null if the user has never agreed to the Callers will need to provide this version when submitting a request to agree to shown ToS." }, "lastAgreementVersioncurrentRequirement": { "$ref": "org.sagebionetworks.repo.model.auth.TermsOfServiceRequirement", "typedescription": "string", "Information about the global ToS Synapse requirements that all users must agree to." } } } |
TermsOfServiceRequirement.json
Code Block | ||
---|---|---|
| ||
{ "description": "The version of ToS thatInformation about the userglobal lastToS agreedSynapse to.requirements that Will be null if the user has never agreed to the ToS." },all users must agree to.", "properties": { "authenticationReceiptrequirementDate": { "type": "string", "descriptionformat": "A valid receipt allows the user to skip extra security checks."date-time", } } } |
New ToS APIs
The following will be the new ToS APIs.
Response | URL | Request | Description | Authorization |
---|---|---|---|---|
TermsOfServiceInfo | GET /termsOfUse2/info | none | Get information about the current ToS | Not Required |
TermsOfServiceInfo | POST /termsOfUse2/requirements | TermsOfServiceRequirement | Sets the global ToS requirements. | Only ACT or Admin may make this call. |
|
|
|
| This will be replaced with the POST /login2/ Response body. |
Note: The starting TermsOfServiceRequirement will be set with minimumTermsOfServiceVersion=0.0.0
and requirementDate=1/1/2011
. All existing users that have agreed to the exiting ToS will meet the starting requirements. This means ACT will need to set the new requirements before users will be required.
Storage Limit APIs
We will use the following pseudo-query to determine the total number of bytes for each storage location and project combination:
Code Block |
---|
SELECT PROJECT_ID, STORAGE_LOCATION_ID, SUM(FILE_SIZE_BYTES) FROM OBJECT_REPLICATION GROUP BY PROJECT_ID, STORAGE_LOCATION_ID; |
Since this query can read millions of rows per project, we will cache (all containers for moves) the results for quick retrieval.
Note: While the following API will work for all combination, clients can “hard-code” the default Synapse storage location ID.
Response | URL | Request | Description | Authorization |
---|---|---|---|---|
ProjectStorageUsage | GET /project/{projectId}/storage/usage | none | Get the information about all combinations for a single project. | The UserEntityPermissions.hasUpload=true for the project. “Plan managers” will have access to this. |
ProjectStorageLocationLimit | POST /project/{projectId}/storage/limit | ProjectStorageLocationLimit | Set the limit for a single combination | Only members of the “plan managers” team may call this service. |
Model Objects
TermsOfServiceInfo.json:
Code Block | ||
---|---|---|
| ||
{ "description": "Information about the current Synapse Terms of Service (ToS).", "properties": { "termsOfServiceUrl "description": "The date/time when the new ToS requirement will go into effect." }, "minimumTermsOfServiceVersion": { "type": "string", "description": "The minimum semantic version of the ToS that all users must agree to by the provided date. Any user that has agreed to this version, or higher, will be required to agree to the latest version of the ToS after the provided date." } } } |
TermsOfServiceStatus.json
Code Block | ||
---|---|---|
| ||
{ "description": "The status of a user's ToS agreement", "properties": { "userId": { "type": "string", "description": "The ID of the user." }, "usersCurrentTermsOfServiceState": { "$ref": "org.sagebionetworks.repo.model.auth.TermsOfServiceState", "description": "Defines the user's current ToS state. Used to guide the UI in what the user needs to do with their ToS agreements. This will always be provided." }, "lastAgreementDate": { "type": "string", "format": "date-time", "description": "The date/time when the user last agreed to the ToS. Will be null if the user has never agreed to the ToS." }, "lastAgreementVersion": { "type": "string", "description": "The version URLof ToS that canthe user belast usedagreed to fetch. Will be null if the user latesthas ToSnever usingagreed anto HTTPSthe GETToS." }, "latestTermsOfServiceVersion": { } } |
TermsOfServiceState.json:
Code Block | ||
---|---|---|
| ||
{ "type": "string", "description": "The semantic version of the latest ToS in the provided URL. Callers will need to provide this version when submitting a request to agree to shown ToS." }, "currentRequirement": ": "The user's current ToS state defines what action if any they will need to take to meet ToS requirements.", "enum": [ { "$refname": "org.sagebionetworks.repo.model.auth.TermsOfServiceRequirementMUST_AGREE_NOW", "description": "Information aboutThe user must agree to the globalnew ToS before they Synapsecan requirementsuse thatthe all users must agree to." } } } |
TermsOfServiceRequirement.json
Code Block | ||
---|---|---|
| ||
{ service." }, { "name": "MUST_AGREE_SOON", "description": "Information about the global ToS Synapse requirements that all users must agree to.", "properties": { "requirementDate": {The user currently has agreed to an older ToS and they will need to agree to the new ToS before new required date." }, { "name": "UP_TO_DATE", "type": "string",description": "The user has agreed to the latest ToS so they are up-to-date" "format": "date-time", } ] } |
ProjectStorageUsage.json
Code Block | ||
---|---|---|
| ||
{ "description": "The date/time when the new ToS requirement will go into effect." },Provides information about file allocations and limits for each storage location associated with a single project.", "properties": { "minimumTermsOfServiceVersionprojectId": { "type": "string", "description": "The minimum semantic versionID of the ToS that all users must agree to by the provided date. Any user that has agreed to this version, or higher, will be required to agree to the latest version of the ToS after the provided date." } } } |
TermsOfServiceStatus.json This data will be provided in the LoginResponse object.
Code Block | ||
---|---|---|
| ||
{ project" }, "locations": { "type": "array", "items": { "$ref": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage" } } } } |
ProjectStorageLocationUsage.json
Code Block | ||
---|---|---|
| ||
{ "description": "Represent the current size and limits for a single project storage location.", "properties": { "storageLocationId": { "type": "string", "description": "The statusID of a user's ToS agreement", "properties": { the storage location" }, "userIdsumFileBytes": { "type": "stringinteger", "description": "The ID of the user total number of bytes, of files, currently associated with this project storage location." }, "hasAgreedToRequiredTermsOfServicemaxAllowedFileBytes": { "type": "boolean", "formattype": "date-timeinteger", "description": "When falsemissing, the user has not agreed to the currently required version of the ToS. True, if the user has agreed." }, "lastAgreementDate": { "type": "string", "format": "date-time", "description": "The date/time when the user last agreed to the ToS. Will be null if the user has never agreed to the ToSthere is not limit for this project storage location. When set, this number represent to the total number of allowed bytes for this project storage location. If the sumFileSizesBytes is greater than this value, then this project storage location is over its limit all new uploads to this project storage location will be blocked." }, "lastAgreementVersionisOverLimit": { "type": "stringboolean", "description": "The version of ToS that the user last agreed to. Will be null if the user has never agreed to the ToS": "When true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this project storage location will be blocked." } } } |
ProjectStorgeUsageProjectStorageLocationLimit.json
Code Block | ||
---|---|---|
| ||
{ "description": "ProvidesSet information about file allocations and limits for each storage location associated withthe limit on the number of files bytes for a single project. storage location", "properties": { "projectId": { "type": "string", "description": "The ID of the project" }, "storageLocationId": { "type": "string", "locations": { "type": "array" "description": "The ID of the storage location" }, "itemsmaxAllowedFileBytes": { "$reftype": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage" } } } } |
ProjectStorageLocationUsage.json
Code Block | ||
---|---|---|
| ||
{ string", "description": "RepresentSets the limit on the current size and limits for a singlenumber of file bytes that can be associated with this project storage location.", "properties": { "storageLocationId": { "type": "string", "description": "The ID of the storage location" }, "sumFileBytes": { } } } |
UploadDestination.json
Code Block | ||
---|---|---|
| ||
{ "description": "The upload destination contains information to start an upload of a file generated according to the underlying <a href=\"${org.sagebionetworks.repo.model.project.StorageLocationSetting}\">StorageLocationSetting</a>.", "type": "integerinterface", "descriptionproperties": "The total number of bytes, of files, currently associated with this project storage location." }, "maxAllowedFileBytes": { { "concreteType": { "type": "integer", "description": "When missingstring", there is not limit for this project storage location. When set, this number represent to the total number of allowed bytes for this project storage location. If the sumFileSizesBytes is greater than this value, then this project storage location is over its limit all new uploads to this project storage location will be blocked."description": "Indicates which implementation this object represents." }, "storageLocationId": { "type": "integer", "description": "the unique id for the storage location, that points to the <a href=\"${org.sagebionetworks.repo.model.project.StorageLocationSetting}\">StorageLocationSetting</a>" }, "isOverLimituploadType": { "type": "boolean", "description": "When true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this project storage location will be blocked.$ref": "org.sagebionetworks.repo.model.file.UploadType" }, } } |
ProjectStorageLocationLimit.json
Code Block | ||
---|---|---|
| ||
{ "description"banner": { "type": "string"Set the limit on the number of files bytes for a single project storage location", "properties": { "projectId, "description": "If set, the client should show this banner every time an upload is initiated" }, "destinationProjectId": { "type": "string", "description": "The ID of the project where this file will be uploaded." }, "storageLocationIdprojectStorageLocationUsage": { "type": "string""$ref": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage", "description": "The ID of theThis object includes information about size and limits associated with this project storage location". }, "maxAllowedFileBytes": { "type": "string", "description": "Sets the limit on the number of file bytes that can be associated with this project storage location Clients should not attempt to upload a file to this location if isOverLimit=true or if (<size_new_file> + sumFileBytes) is greater than maxAllowedFileBytes." } } } |