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: shortDescription → 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/history | AccessApprovalHistoryRequest | AccessApprovalHistoryResponse | Is POST /accessApproval/group enough? Only difference is no history and sort, but sort could probably be added to that service. | 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. |
GET/POST /accessRequirement/{id}/bundle | We could also just do a service to get the related projects for an AR, since a service already exists for fetching the ACL |
Objects
AccessRequirementBundle
{
"title":"Access Requirement Bundle",
"description":"Access Requirement and related objects",
"properties": {
"accessRequirement":{
"$ref":"org.sagebionetworks.repo.model.AccessRequirement"
},
"accessControlList":{
"$ref": "org.sagebionetworks.repo.model.AccessControlList"
},
"relatedProjects":{
"type": "array",
"items": {
"type": "string" // synIds
}
}
}
}
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."
}
}
}
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.AccessRequirementBundle"
}
"description":"The results of an access requirement search"
},
}
}
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."
},
"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."
},
"status": {
"type": "array",
"items": {
"$ref": "org.sagebionetworks.repo.model.dataaccess.SubmissionStatus"
},
"description": "Filter Data Access Submissions to show only those with the specified SubmissionStatus."
},
"sort": {
"type": "enumeration",
"values": ["CREATED_ON_ASC", "CREATED_ON_DESC"],
"default": "CREATED_ON_DESC"
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
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.Submission"
},
"description":"Submissions matching the search parameters"
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
AccessApprovalHistoryRequest
{
"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."
}
}
}
AccessApprovalHistoryResponse
{
"title":"Access Approval History Response",
"description":"The results of an Access Approval History Request",
"properties": {
"results": {
"type":"array",
"items": {
"$ref": "org.sagebionetworks.repo.model.AccessApproval"
},
"description":"The history of Access Approvals matching the search parameters"
},
"nextPageToken": {
"type": "string",
"description": "A token used to get the next page of a particular search query."
}
}
}
Deprecations
TBD – we should identify which (if any) services would be unnecessary after these changes are made and deprecate them