Versions Compared

Version Old Version 6 New Version 7
Changes made by

John Hill

John Hill

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

...

languagejson

...

. 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.

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

POST /termsOfUse2/status

none

Get the current user’s ToS status. Used to determine if the user needs to agree to the new ToS

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.

UploadDestinationInfo

GET /entity/{id}/uploadDestination2

Replacement for GET /entity/{id}/uploadDestination

Same as GET /entity/{id}/uploadDestination

Checking Limits Before Upload

Before a client uploads a file to a project or folder, the client will first call GET /entity/{id}/uploadDestination2 (new service). The resulting UploadDestinationInfo object provides the storage location ID to be used for the upload just the the old version of this service. However, the new UploadDestinationInfo object also includes information about the project storage location 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

Model Objects

LoginResponse.json

Code Block
languagejson
{
	"title": "LoginResponse",
	"description": "Holds a session token used for short-term authentication with Synapse",
	"properties": {
		"sessionToken": {
			"type": "string",
			"description": "(deprecated) A token that identifies the user"
		},
		"accessToken": {
			"type": "string",
			"description": "A token that authorizes subsequent requests"
		},
		"acceptsTermsOfUse": {
			"type": "boolean",
			"description": "When false, the user has not agreed to the currently required version of the ToS. This user will need to agree the the latest ToS by the requirement date.  True, if the user has agreed."
		},
		"accessTokenlastAgreementDate": {
			"type": "string",
			"description": "A token that authorizes subsequent requests"
		},
		"acceptsTermsOfUse": {",
			"typeformat": "booleandate-time",
			"description": "When false,The date/time when the user haslast not agreed to the currently required version of the ToS. This user will need to agree the the latest ToS by to the requirement dateToS. Will True,be null if the user has never agreed to the ToS."
		},
		"lastAgreementDatelastAgreementVersion": {
			"type": "string",
			"formatdescription": "date-time",
			"description": "The date/time whenThe version of ToS that the user last agreed to. the ToS. Will be null if the user has never agreed to the ToS."
		},
		"lastAgreementVersionauthenticationReceipt": {
			"type": "string",
			"description": "The versionA ofvalid ToSreceipt thatallows the user to lastskip extra agreedsecurity tochecks."
 Will be null if		}
	}
}

TermsOfServiceInfo.json:

Code Block
languagejson
{
	"description": "Information about the usercurrent hasSynapse neverTerms agreed toof theService (ToS).",
		},"properties": {
		"authenticationReceipttermsOfServiceUrl": {
			"type": "string",
			"description": "A valid receipt allows the user to skip extra security checks."
		}
	}
}

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

POST /termsOfUse2/status

none

Get the current user’s ToS status. Used to determine if the user needs to agree to the new ToS

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
languagejson
{
	"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."
		},
		"latestTermsOfServiceVersionThe URL that can be used to fetch the latest ToS using an HTTPS GET."
		},
		"latestTermsOfServiceVersion": {
			"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": {
			"$ref": "org.sagebionetworks.repo.model.auth.TermsOfServiceRequirement",
			"description": "Information about the global ToS Synapse requirements that all users must agree to."
		}
	}
}

TermsOfServiceRequirement.json

Code Block
languagejson
{
	"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 This data will be provided in the LoginResponse object.

Code Block
languagejson
{
	"description": "The status of a user's ToS agreement",
	"properties": {
		"userId": {
			"type": "string",
			"description": "The semanticID 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 the user."
		},
		"currentRequirementhasAgreedToRequiredTermsOfService": {
			"$reftype": "org.sagebionetworks.repo.model.auth.TermsOfServiceRequirement",
			"description": "Information about the global ToS Synapse requirements that all users must agree to."boolean",
		}
	}
}

TermsOfServiceRequirement.json

Code Block
languagejson
{
		"format": "date-time",
			"description": "Information about the global ToS Synapse requirements that all users must agree to.",
	"properties": {
		"requirementDateWhen 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 new user last agreed to the ToS requirement will go into effect. Will be null if the user has never agreed to the ToS."
		},
		"minimumTermsOfServiceVersionlastAgreementVersion": {
			"type": "string",
			"description": "The minimum semantic version of the ToS that all users must agree to by the provided date.  Any user that haslast agreed to. this version, or higher, will Will be required to agree tonull if the latest versionuser ofhas thenever ToSagreed afterto the provided dateToS."
		}
	}
}

TermsOfServiceStatusProjectStorgeUsage.json This data will be provided in the LoginResponse object.

Code Block
languagejson
{
	"description": "The status ofProvides information about file allocations and limits for each storage location associated with a user's ToS agreementsingle project.",
	"properties": {
		"userIdprojectId": {
			"type": "string",
			"description": "The ID of the user.project"
		},
		"hasAgreedToRequiredTermsOfServicelocations": {
			"type": "booleanarray",
			"formatitems": {
				"$ref": "date-time",
		"org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage"
			}
		}
	}
}

ProjectStorageLocationUsage.json

Code Block
languagejson
{
	"description": "WhenRepresent false, the usercurrent hassize notand agreedlimits tofor thea currentlysingle requiredproject version of the ToS.  True, if the user has agreed."
		},
		"lastAgreementDatestorage location.",
	"properties": {
			"typestorageLocationId": "string",{
			"formattype": "date-timestring",
			"description": "The date/timeID whenof the user last agreed to the ToS. Will be null if the user has never agreed to the ToS storage location"
		},
		"sumFileBytes": {
			"type": "integer",
			"description": "The total number of bytes, of files, currently associated with this project storage location."
		},
		"lastAgreementVersionmaxAllowedFileBytes": {
			"type": "stringinteger",
			"description": "TheWhen versionmissing, of ToS that the user last agreed to.  Will be null if the user has never agreedthere is not limit for this project storage location.  When set, this number represent to the total ToS."
		}
	}
}

ProjectStorgeUsage.json

Code Block
languagejson
{
	"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"
		},
		"locations": {
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage"
			}
		}
	}
}

ProjectStorageLocationUsage.json

Code Block
languagejson
{
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."
		},
		"isOverLimit": {
			"type": "boolean",
			"description": "Represent the current size and limits for a singleWhen true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this project storage location.",
	"properties": {
		"storageLocationId": { will be blocked."
			"type": "string",
		}
	}
}

ProjectStorageLocationLimit.json

Code Block
languagejson
{
	"description": "The IDSet the limit on the number of thefiles bytes for a single project storage location",
		},"properties": {
		"sumFileBytesprojectId": {
			"type": "integerstring",
			"description": "The totalID number of bytes, of files, currently associated with this project storage location.the project"
		},
		"maxAllowedFileBytesstorageLocationId": {
			"type": "integerstring",
			"description": "When missing, there is not limit for this project storage location.  When set, this number represent to the total number of allowed bytes for this project "The ID of the storage location."
 If the sumFileSizesBytes is greater than this value, then this project storage location is over its limit all new uploads to		},
		"maxAllowedFileBytes": {
			"type": "string",
			"description": "Sets the limit on the number of file bytes that can be associated with this project storage location will be blocked."
		},
		"isOverLimit": {
			"type": "boolean",
		}
}

UploadDestinationInfo.json

Code Block
languagejson
{
	"description": "When true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this project storage location will be blocked."
		}
	}
}

ProjectStorageLocationLimit.json

Code Block
languagejson
{
Provides information about the storage location that should be used when uploading a file and information about the destination project and limits that may apply",
	"properties": {
		"uploadDestination": {
			"$ref": "org.sagebionetworks.repo.model.file.UploadDestination",
			"description": "Set the limit on the numberDetails of the filesstorage byteslocation forwhere athe singlefile projectshould storagebe locationupload.",
	"properties": {		},
		"projectIddestinationProjectId": {
			"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."
		}
	}
}