Versions Compared

Key

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

...

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

UploadDestinationInfo

Checking Limits Before Upload

Before a client uploads a file to a project or folder, the client will first call GET /entity/{id}

...

/

...

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

...

languagejson

...

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

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."
		},
		"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": "(deprecated) A tokenThe version of ToS that identifies the user"
		},
		"accessToken": {
			"type": "string",
			"description": "A token that authorizes subsequent requests last agreed to.  Will be null if the user has never agreed to the ToS."
		},
		"acceptsTermsOfUseauthenticationReceipt": {
			"type": "booleanstring",
			"description": "When false, the user has not agreed to the currently required version ofA valid receipt allows the ToS.user Thisto userskip willextra needsecurity to agree the the latest ToS by the requirement date.  True, if the user has agreed."
		},
		"lastAgreementDatechecks."
		}
	}
}

TermsOfServiceInfo.json:

Code Block
languagejson
{
	"description": "Information about the current Synapse Terms of Service (ToS).",
	"properties": {
			"typetermsOfServiceUrl": "string",{
			"formattype": "date-timestring",
			"description": "The date/timeURL whenthat thecan user last agreed to the ToS. Will be null ifbe used to fetch the userlatest hasToS neverusing agreedan toHTTPS the ToSGET."
		},
		"lastAgreementVersionlatestTermsOfServiceVersion": {
			"type": "string",
			"description": "The semantic version of the latest ToS thatin the user last agreedprovided URL.  Callers will need to. provide Willthis beversion nullwhen ifsubmitting thea userrequest hasto neveragree agreed to theshown ToS."
		},
		"authenticationReceiptcurrentRequirement": {
			"type$ref": "string",
			"description": "A valid receipt allows the user to skip extra security checks."
		}
	}
}

TermsOfServiceInfo.json:

Code Block
languagejson
{
org.sagebionetworks.repo.model.auth.TermsOfServiceRequirement",
			"description": "Information about the global currentToS Synapse Termsrequirements ofthat Service (ToS).",
	"properties": {
		"termsOfServiceUrl": {all users must agree to."
			"type": "string",
		}
	}
}

TermsOfServiceRequirement.json

Code Block
languagejson
{
	"description": "TheInformation URLabout thatthe canglobal beToS usedSynapse torequirements fetchthat theall latestusers ToSmust using an HTTPS GET."
		},
		"latestTermsOfServiceVersion": {agree to.",
	"properties": {
		"requirementDate": {
			"type": "string",
			"typeformat": "stringdate-time",
			"description": "The semantic version ofdate/time when the latestnew ToS in the provided URL.  Callers requirement will need to provide this version when submitting a request to agree to shown ToSgo into effect."
		},
		"currentRequirementminimumTermsOfServiceVersion": {
			"$reftype": "org.sagebionetworks.repo.model.auth.TermsOfServiceRequirementstring",
			"description": "InformationThe aboutminimum thesemantic globalversion ToSof Synapsethe requirementsToS 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",
		 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 date/time when the new ToS requirement will go into effect."
		},status of a user's ToS agreement",
	"properties": {
		"minimumTermsOfServiceVersionuserId": {
			"type": "string",
			"description": "The minimumID 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 latestuser."
		},
		"hasAgreedToRequiredTermsOfService": {
			"type": "boolean",
			"format": "date-time",
			"description": "When false, the user has not agreed to the currently required version of the ToS.  True, afterif the user providedhas dateagreed."
		},
	}
}

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

Code Block
languagejson
{
			"lastAgreementDate": {
			"type": "string",
			"format": "date-time",
			"description": "The statusdate/time ofwhen athe user's ToS agreement",
	"properties": {
		"userId": {
			"type": "string",
			"description": "The ID of the user last agreed to the ToS. Will be null if the user has never agreed to the ToS."
		},
		"hasAgreedToRequiredTermsOfServicelastAgreementVersion": {
			"type": "booleanstring",
			"format": "date-time",
			"description": "WhenThe false,version theof user has not agreed toToS that the currentlyuser requiredlast versionagreed ofto. the ToS.Will be True,null if the user has never agreed to the ToS."
		},
		"lastAgreementDate": {
			"type": "string",
			"format": "date-time",
			}
}

ProjectStorageUsage.json

Code Block
languagejson
{
	"description": "TheProvides date/timeinformation whenabout thefile userallocations lastand agreedlimits tofor theeach ToS.storage Willlocation beassociated nullwith if the user has never agreed to the ToS."
		},a single project.",
	"properties": {
		"lastAgreementVersionprojectId": {
			"type": "string",
			"description": "The versionID of ToS that the user last agreed to.  Will be null if the user has never agreed to the ToS."project"
		},
		"locations": {
			"type": "array",
			"items": {
				"$ref": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage"
			}
		}
	}
}

ProjectStorgeUsageProjectStorageLocationUsage.json

Code Block
languagejson
{
	"description": "ProvidesRepresent informationthe aboutcurrent file allocationssize and limits for each storage location associated with for a single project storage location.",
	"properties": {
		"projectIdstorageLocationId": {
			"type": "string",
			"description": "The ID of the storage projectlocation"
		},
		"locationssumFileBytes": {
			"type": "arrayinteger",
			"description": "The total number of bytes, of files, currently associated with this project storage location."
		},
		"itemsmaxAllowedFileBytes": {
				"$reftype": "org.sagebionetworks.repo.model.limits.ProjectStorageLocationUsage"integer",
			}
		}
	}
}

ProjectStorageLocationUsage.json

Code Block
languagejson
{
	"description": "Represent the current size and limits for a single "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 storage location.",
	"properties": {
		"storageLocationId": {
			"type": "string",
			"description": "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 this project storage location will be blocked."
		},
		"sumFileBytesisOverLimit": {
			"type": "integerboolean",
			"description": "The total number of bytes, of files, currently associated withWhen true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads to this project storage location will be blocked."
		},
		"maxAllowedFileBytes": {
			"type": "integer",
		}
}

ProjectStorageLocationLimit.json

Code Block
languagejson
{
	"description": "When missing, there is notSet the limit for this project storage location.  When set, this number represent to the totalon the number of allowedfiles bytes for a thissingle 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.",
	"properties": {
		"projectId": {
			"type": "string",
			"description": "The ID of the project"
		},
		"storageLocationId": {
			"type": "string",
			"description": "The ID of the storage location"
		},
		"isOverLimitmaxAllowedFileBytes": {
			"type": "booleanstring",
			"description": "When true, sumFileSizesBytes is greater than maxAllowedFileSizeBytes and all new uploads toSets the limit on the number of file bytes that can be associated with this project storage location will be blocked."
		}
	}
}

ProjectStorageLocationLimitUploadDestination.json

Code Block
languagejson
{
	"description": "Set the limit on the number of files bytes for a single project storage location",
	"properties": {
		"projectId": {
			"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": "stringinterface",
			"descriptionproperties": "The ID of the project"
		},
		"storageLocationId{
        "concreteType": {
			
            "type": "string",
			"description": "The ID of the storage location" 		}, 		"maxAllowedFileBytes": { 			"type": "string", 			"description": "SetsIndicates thewhich limitimplementation on the number of file bytes that can be associated with this project storage location."
		}
	}
}

UploadDestinationInfo.json

Code Block
languagejson
{
	"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": {
		"uploadDestinationthis 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>"
		},
		"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."
		}
	}
}

...