Versions Compared

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

POST PUT /termsOfUse2/requirements

TermsOfServiceRequirement

Sets the global ToS requirements.

Only ACT or Admin may make this call.

TermsOfServiceStatus

POST 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 will be replaced with the POST /login2/ Response bodycall 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.

...

Note: While the following API will work for all combination, clients can “hard-code” the default Synapse storage location ID.

...

Response

...

URL

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.

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

Model Objects

LoginResponse.json

...

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
languagejson
{
	"titledescription": "LoginResponse",
	"description": "Holds a session token used for short-term authentication with SynapseInformation about the current Synapse Terms of Service (ToS).",
	"properties": {
		"sessionTokentermsOfServiceUrl": {
			"type": "string",
			"description": "(deprecated) A token that identifies the userThe URL that can be used to fetch the latest ToS using an HTTPS GET."
		},
		"accessTokenlatestTermsOfServiceVersion": {
			"type": "string",
			"description": "AThe tokensemantic thatversion authorizesof subsequentthe requests"
latest ToS in the provided URL.  Callers will need to provide this version when submitting a request to agree to shown ToS."
		},
		"acceptsTermsOfUsecurrentRequirement": {
			"type$ref": "boolean",
			org.sagebionetworks.repo.model.auth.TermsOfServiceRequirement",
			"description": "WhenInformation false,about the userglobal hasToS notSynapse agreedrequirements tothat theall currentlyusers requiredmust version of the ToS. This user will need to agree the the latest ToS by the requirement date.  True, if the user has agreed."
		},
		"lastAgreementDateagree 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 usernew lastToS agreedrequirement towill thego ToS. Will be null if the user has never agreed to the ToSinto effect."
		},
		"lastAgreementVersionminimumTermsOfServiceVersion": {
			"type": "string",
			"description": "The minimum semantic version of the ToS that theall userusers lastmust agreedagree to. by Willthe beprovided nulldate. if theAny user that has never agreed to this version, or higher, will be required to agree to the latest version of the ToS after the provided date."
		},
		"authenticationReceipt": }
}

TermsOfServiceStatus.json

Code Block
languagejson
{
			"typedescription": "The status of a user's ToS agreement",
	"properties": {
		"userId": {
			"type": "string",
			"description": "AThe validID receipt allowsof the user to skip extra security checks."
		}
	}
}

TermsOfServiceInfo.json:

Code Block
languagejson
{
."
		},
		"usersCurrentTermsOfServiceState": {
			"$ref": "org.sagebionetworks.repo.model.auth.TermsOfServiceState",
			"description": "InformationDefines aboutthe theuser's current Synapse Terms of Service (ToS).",
	"properties": {ToS state. Used to guide the UI in what the user needs to do with their ToS agreements.  This will always be provided."
		},
		"termsOfServiceUrllastAgreementDate": {
			"type": "string",
			"descriptionformat": "date-time",
			"description": "The date/time URLwhen thatthe canuser belast usedagreed to fetch the ToS. Will be null if the latestuser has ToSnever usingagreed anto HTTPSthe GETToS."
		},
		"latestTermsOfServiceVersionlastAgreementVersion": {
			"type": "string",
			"description": "The semantic version of the latest ToS inthat the provideduser URL.last agreed Callersto. will needWill tobe providenull thisif versionthe whenuser submittinghas anever requestagreed to agree tothe shown ToS."
		},
	}
}

TermsOfServiceState.json:

Code Block
languagejson
{
	"currentRequirementtype": {
			"$ref": "org.sagebionetworks.repo.model.auth.TermsOfServiceRequirement"string",
			"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 toThe user's current ToS state defines what action if any they will need to take to meet ToS requirements.",
	"propertiesenum": {[
		"requirementDate": {
			"typename": "string",
			"format": "date-timeMUST_AGREE_NOW",
			"description": "The date/time when user must agree to the new ToS requirementbefore they willcan gouse intothe effectservice."
		},
		"minimumTermsOfServiceVersion": {
			"typename": "stringMUST_AGREE_SOON",
			"description": "The minimumuser semanticcurrently versionhas of theagreed to an older ToS and thatthey allwill usersneed mustto agree to by the providednew date.ToS before Anynew userrequired that has agreed to this version, or higher, will be required to agreedate."
		},
		{
			"name": "UP_TO_DATE",
			"description": "The user has agreed to the latest version of the ToS afterso thethey providedare up-to-date."
		}
	}]
}

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

Code Block
languagejson
{
	"description": "TheProvides statusinformation ofabout a user's ToS agreementfile allocations and limits for each storage location associated with a single project.",
	"properties": {
		"userIdprojectId": {
			"type": "string",
			"description": "The ID of the user.project"
		},
		"hasAgreedToRequiredTermsOfServicelocations": {
			"type": "booleanarray",
			"formatitems": "date-time",
{
				"description$ref": "When false, the user has not agreed to the currently required version of the ToS.  True, if the user has agreed."
		},
		"lastAgreementDateorg.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage"
			}
		}
	}
}

ProjectStorageLocationUsage.json

Code Block
languagejson
{
	"description": "Represent the current size and limits for a single project storage location.",
	"properties": {
			"typestorageLocationId": "string",{
			"formattype": "date-timestring",
			"description": "The date/timeID whenof the userstorage last agreed to the ToS. Will be null if the user has never agreed to the ToSlocation"
		},
		"sumFileBytes": {
			"type": "integer",
			"description": "The total number of bytes, of files, currently associated with this project storage location."
		},
		"lastAgreementVersionmaxAllowedFileBytes": {
			"type": "stringinteger",
			"description": "TheWhen versionmissing, ofthere ToSis not thatlimit thefor userthis lastproject agreedstorage tolocation.  When set, Willthis benumber nullrepresent ifto the user has never agreed to the 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 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."
		},
		"locationsisOverLimit": {
			"type": "arrayboolean",
			"itemsdescription": { 				"$ref": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage"
			}"When true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this project storage location will be blocked."
		}
	}
}

ProjectStorageLocationUsageProjectStorageLocationLimit.json

Code Block
languagejson
{
	"description": "RepresentSet the currentlimit sizeon andthe limits number of files bytes for a single project storage location.",
	"properties": {
		"storageLocationIdprojectId": {
			"type": "string",
			"description": "The ID of the storage locationproject"
		},
		"sumFileBytesstorageLocationId": {
			"type": "integerstring",
			"description": "The total numberID of bytes, of files, currently associated with this project the storage location."
		},
		"maxAllowedFileBytes": {
			"type": "integerstring",
			"description": "WhenSets missing,the therelimit ison notthe limitnumber forof this file bytes that can be associated with this project storage location."
		}
	}
}

UploadDestination.json

Code Block
languagejson
{
 When set, this number represent	"description": "The upload destination contains information to thestart totalan numberupload of alloweda bytesfile forgenerated this project storage location.  Ifaccording to the sumFileSizesBytesunderlying 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": "When true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this project storage location will be blocked."
		}
	}
}

ProjectStorageLocationLimit.json

Code Block
languagejson
{
	"description": "Set the limit on the number of files bytes for a single project storage location",
	"properties": {
		"projectId": {
			<a href=\"${org.sagebionetworks.repo.model.project.StorageLocationSetting}\">StorageLocationSetting</a>.",
	"type": "stringinterface",
			"descriptionproperties": {
  "The ID of the project" 		}, 		"storageLocationIdconcreteType": {
			
            "type": "string",
			"description": "The ID of the storage location" 		}, 		"maxAllowedFileBytes": { 			"type": "string", 			"description": "SetsIndicates thewhich limitimplementation onthis the number of file bytes that can be associated with this project storage location."
		}
	}
}

UploadDestinationInfo.json

Code Block
languagejson
{
object represents."
        },
		"storageLocationId": {
			"type": "integer",
			"description": "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 unique id for the storage location, that points to the <a href=\"${org.sagebionetworks.repo.model.project.StorageLocationSetting}\">StorageLocationSetting</a>"
		},
		"uploadType": {
			"$ref": "org.sagebionetworks.repo.model.file.UploadDestinationUploadType"
		},
		"banner": {
			"type": "string",
			"description": "DetailsIf ofset, the client storageshould locationshow wherethis thebanner fileevery shouldtime bean upload. is initiated"
		},
		"destinationProjectId": {
			"type": "string",
			"description": "The ID of the project where this file will be uploaded."
		},
		"projectStorageLocationUsage": {
			"$ref": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage",
			"description": "This object includes information about size and limits 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."
		}
	}
}

...