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 Manually enabled/disabled as a profile setting Request to see if any ARs exist with the caller having access via ACL (boolean or return the list of ARs)	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.

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": {
        "nameSubstring":{
            "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

Extensible Data Management Phase 1 API Changes

Object Changes

Services

Objects

Deprecations