This page will provided detailed specifications for new/changed APIs as required by Phase 1 of API Changes to support: Extension of Data Access Management to Users outside of Sage ACT.
Object Changes
Access Requirement: description → name
UI only or do we need a migration plan? We would need to
Update Synapse Web Client
Update Synapse React Client
Update all portals and SWC to use new versions of React Client
Likely cannot enforce uniqueness, but maybe we could warn when a new AR name collides with an existing one in the UI.
Enforce non-null/non-empty? Null/empty names could take on the requirement ID as a name.
Services
Endpoint | Parameters/Object | Returns | Notes/Questions | Stories |
|---|---|---|---|---|
??? | Need a way to identify the caller as a reviewer so we can determine if we should show the navbar item in the web client. This could be
| As a reviewer, I need an intuitive way to access the ACT/Reviewer dashboard so I can review pending requests, troubleshoot user access, and perform other data access tasks. | ||
POST /accessRequirement/search | AccessRequirementSearchRequest | AccessRequirementSearchResponse | For all services, when to allow array filters? No auth required; ARs are public info Special behavior if the reviewerID is the ACT? Is this good enough for search? | As an ACT member, I want to be able to query for existing access requirements so I can inspect or modify them without having to navigate to a specific entity controlled by the AR. As an ACT member, I want to be able to find an AR ID using the AR name so that I can filter other queries by AR without knowing the AR ID. |
POST /dataAccessSubmission/search | DataAccessSubmissionSearchRequest | DataAccessSubmissionSearchResponse | Auth required ACT member will see all submissions. If the caller is not ACT, they will only see submissions on ARs for which they have the “REVIEW_SUBMISSIONS” permission. What to do about https://docs.synapse.org/rest/GET/dataAccessSubmission/openSubmissions.html ? Deprecate? | See https://sagebionetworks.jira.com/wiki/spaces/~557058fa14d697877047ec802a3e459a04898e/pages/edit-v2/2617442828?draftShareId=316dfb35-cc6b-4dc2-9e97-c6a4bf025f02 – need to refine This will support both the “Submissions” tab for all reviewers and the “Access History” tab for ACT |
POST /accessApproval/search | AccessApprovalHistoryRequest | AccessApprovalHistoryResponse | Is POST /accessApproval/group enough? Only difference is no history and sort, but sort could probably be added to that service. Status by submitter - (submitter, AR ID) is primary key | As an ACT user, I want to see the entire history of Access Approvals so I can understand why a user may have gained or lost access on an access requirement. |
Objects
AccessRequirementSearchRequest
{
"title":"Access Requirement Search Request",
"description":"Describes the parameters for searching Access Requirements",
"properties": {
"nameContains":{
"type":"string",
"description":"A substring used to filter Access Requirements by name"
},
"relatedProjectId":{
"type":"string",
"description":"A synID used to filter Access Requirements to retrieve only those that have been applied within a particular project."
},
"reviewerId":{
"type":"number",
"description":"A principal ID used to filter Access Requirements to retrieve only those with the user/ or team on the ACL."
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
AccessRequirementSearchResult
{
"$id": "org.sagebionetworks.repo.model.AccessRequirementSearchResult"
"title":"Access Requirement Search Result Item",
"description":"Result item of an Access Requirement search"
"properties": {
"accessRequirementId":{
"type": "string"
},
"name": {
"type": "string"
}
"reviewerIds":{
"type": "array",
"description": "Principal IDs of the reviewers of the AR."
"items": {
"type": "number"
}
},
"relatedProjectIds":{
"type": "array",
"items": {
"type": "string"
}
},
"modifiedOn": {
"type": "string",
"format":"date-time"
}
}
}
AccessRequirementSearchResponse
{
"title":"Access Requirement Search Response",
"description":"Describes the response object for an Access Requirement search",
"properties": {
"results":{
"type":"array",
"items": {
"$ref": "org.sagebionetworks.repo.model.AccessRequirementSearchResult"
}
"description":"The results of an access requirement search"
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
DataAccessSubmissionSearchRequest
{
"title":"Access Requirement Search Request",
"description":"Describes the parameters for searching Data Access Submissions",
"properties": {
"accessRequirementId": {
"type":"string",
"description": "Filter submissions by their Access Requirement ID"
},
"accessorId": {
"type":"string",
"description":"A principal ID used to filter submissions by accessors on the submission."
},
"reviewerFilter": {
// TODO: check this field with stakeholders
"type": "string",
"enum": [
"ACT_ONLY",
"DELEGATED_ONLY"
],
"required": false
},
"reviewerId": {
"type":"number",
"description":"A principal ID used to filter Access Requirements to retrieve only those with the specified user or team on the ACL."
},
"sort": {
"type": "object",
"properties": {
"field": {
"type": "string",
"const": "CREATED_ON"
}
"direction": {
"$ref": "org.sagebionetworks.repo.model.SortDirection"
}
}
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
DataAccessSubmissionSearchResult
{
"$id": "org.sagebionetworks.repo.model.dataaccess.DataAccessSubmissionSearchResult"
"title":"Data Access Submission Search Result Item",
"description": "",
"properties": {
"submissionId": {
"type": "string"
},
"accessRequirementId":{
"type": "string"
},
"accessRequirementName": {
"type": "string"
},
"reviewerIds":{
"type": "array"
},
"submitterId": {
"description": "The principal ID of the person who created the submission."
"type": "number"
},
"accessorIds": {
"type": "array",
"description": "The principal IDs of the users who are accessors on the submission",
"items": {
"type": "number"
}
},
"state": {
"$ref": "org.sagebionetworks.repo.model.dataaccess.SubmissionState"
},
"createdOn": {
"type": "string",
"format":"date-time"
}
}
}
DataAccessSubmissionSearchResponse
{
"title":"Access Requirement Search Response",
"description":"Describes the parameters for searching Access Requirements",
"properties": {
"results": {
"type":"array",
"items": {
"$ref": "org.sagebionetworks.repo.model.dataaccess.DataAccessSubmissionSearchResult"
},
"description":"Submissions matching the search parameters"
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
AccessApprovalSearchRequest
{
"title":"Access Approval History Request",
"description":"Describes the parameters for searching through the history of Access Approvals for a particular accessor",
"properties": {
"accessorId": {
"type":"number",
"description": "The principal ID of the accessor.",
"required": true
},
"accessRequirementId": {
"type": "number",
"description": "The access requirement for which access approvals should be shown.",
"required": false
},
"sort": {
"type": "enumeration",
"values": ["MODIFIED_ON_ASC", "MODIFIED_ON_DESC", "EXPIRED_ON_ASC", "EXPIRED_ON_DESC"],
"default": "MODIFIED_ON_DESC"
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
AccessApprovalSearchResult
{
"$id": "org.sagebionetworks.repo.model.AccessApprovalSearchResult"
"title":"Access Approval Search Result Item",
"description": "The result item in an Access Approval search",
"properties": {
"id": {
"description": "The ID of the Access Approval",
"type": "string"
},
"requirementId":{
"type": "string"
},
"requirementName": {
"type": "string"
},
"reviewerIds":{
"type": "array"
},
"submitterId": {
"description": "The principal ID of the person who created the submission."
"type": "number"
},
"state": {
"$ref": "org.sagebionetworks.repo.model.ApprovalState"
},
"modifiedOn": {
"type": "string",
"format":"date-time"
},
"expiredOn": {
"type": "string",
"format": "date-time",
"description": "The date this object will be expired.",
"title": "Expired On",
"transient": true
}
}
}
AccessApprovalSearchResponse
{
"title":"Access Approval Search Response",
"description":"The results of an Access Approval History Request",
"properties": {
"results": {
"type":"array",
"items": {
"$ref": "org.sagebionetworks.repo.model.AccessApprovalSearchResult"
},
"description":"The matching Access Approval information corresponding to the search parameters"
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}