Skip to end of banner
Go to start of banner

Extensible Data Management Phase 1 API Changes

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

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

  • No labels