API Changes for ToS and Managed Plan Rollout
- John Hill
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.
We will also update the LoginResponse object returned by: POST /login2 to include the more information the user’s ToS status. 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:
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:
if (sumFileBytes + newFileSize > maxAllowedFileBytes) then block uploadSince we are changing the UploadDestionation object, GET /entity/{id}/uploadDestination/{storageLocationId} service will also return the new project limit information.
Model Objects
TermsOfServiceInfo.json:
TermsOfServiceRequirement.json
TermsOfServiceStatus.json
TermsOfServiceState.json:
ProjectStorageUsage.json
ProjectStorageLocationUsage.json
ProjectStorageLocationLimit.json
UploadDestination.json