For information on the requirements for these API changes see: Rollout of the new Terms of Service and Managed Plans.
Agreeing to the ToS
Currently, clients use the following API to set that the user has agreed to the ToS: POST /termsOfUse2
Rather than add a new service, we will update the existing service’s request object as follows:
AccessToken.json
{
"title": "Access Token",
"description": "Request to agree to the terms of service.",
"properties": {
"accessToken": {
"type": "string",
"description": "An access token of the user that is agreeing to the ToS."
},
"termsOfServiceVersion": {
"type": "string",
"description": "The semantic version of the ToS that the user read and agreed to. Required. If a client does not provide this value, then a default value of '0.0.0' will be used indicating that the original (and deprecated) ToS was used."
}
}
}
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.
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. |
TermsOfServiceStatus | GET /termsOfUse2/{userId}/status | none | Get the current user’s ToS status. Used to determine if the user needs to agree to the new ToS | A user can only get their own status. |
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:
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 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 |
|---|---|---|---|---|
ProjectStorageInfo | GET /project/{projectId}/storage/info | none | Get the information about all combinations for a single project. | The UserEntityPermissions.hasUpload=true for the project |
CombinationLimit | POST /project/{projectId}/storage/limit | CombinationLimit | Set the limit for a single combination | Only members of the “plan managers” team may call this service. |
Model Objects
TermsOfServiceInfo.json:
{
"description": "Information about the current Synapse Terms of Service (ToS).",
"properties": {
"termsOfServiceUrl": {
"type": "string",
"description": "The URL that can be used to fetch the current ToS using an HTTPS GET."
},
"termsOfServiceVersion": {
"type": "string",
"description": "The semantic version of the ToS in the provided URL. Callers will need to provide this version when submitting a request to agree to shown ToS."
},
"currentRequirement": {
"$ref": "org.sagebionetworks.repo.model.auth.TermsOfServiceRequirement",
"description": "Information about the global ToS Synapse requirements that all users must agree to."
}
}
}
TermsOfServiceRequirement.json
{
"description": "Information about the global ToS Synapse requirements that all users must agree to.",
"properties": {
"requirementDate": {
"type": "string",
"format": "date-time",
"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
{
"description": "The status of a user's ToS agreement",
"properties": {
"userId": {
"type": "string",
"description": "The ID of the user."
},
"hasAgreedToRequiredTermsOfService": {
"type": "boolean",
"format": "date-time",
"description": "When false, 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 ToS."
},
"lastAgreementVersion": {
"type": "string",
"description": "The version of ToS that the user last agreed to. Will be null if the user has never agreed to the ToS."
}
}
}
ProjectStorgeInfo.json
{
"description": "Provides information about file allocations and limits for each storage location associated with a single project.",
"properties": {
"projectId": {
"type": "string",
"description": "The ID of the project"
},
"combinations": {
"type": "array",
"items": {
"$ref": "org.sagebionetworks.repo.model.limits.ProjectStorageCombination"
}
}
}
}
ProjectStorageCombination.json
{
"description": "Represent the current size and limits for a single storage location and project combination.",
"properties": {
"storageLocationId": {
"type": "string",
"description": "The ID of the storage location"
},
"sumFileBytes": {
"type": "integer",
"description": "The total number of bytes, of files, currently associated with this combination."
},
"maxAllowedFileBytes": {
"type": "integer",
"description": "When missing, there is not limit for this combination. When set, this number represent to the total number of allowed bytes for this combination. If the sumFileSizesBytes is greater than this value, then this combination is over its limit all new uploads to this combination will be blocked."
},
"isOverLimit": {
"type": "boolean",
"description": "When true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this combination will be blocked."
}
}
}
CombinationLimit.json
{
"description": "Set the limit on the number of files bytes for storage location and project combination.",
"properties": {
"projectId": {
"type": "string",
"description": "The ID of the project"
},
"storageLocationId": {
"type": "string",
"description": "The ID of the storage location"
},
"maxAllowedFileBytes": {
"type": "string",
"description": "Sets the limit on the number of file bytes that can be associated with this combination."
}
}
}