Access Approval Services
The Access Approval services manage the fulfillment of Access Requirements, on a per-user basis. (See Access Requirement Services for more information.) Most of the Access Approval services are available only to members of the Synapse Access and Compliance Team (ACT).
Web Services
Resource | Description |
---|---|
POST /accessApproval | Create an Access Approval, thereby fulfilling an Access Requirement for a given user. Self-signed Access Approvals may be generated by the user being … |
GET /accessApproval/{approvalId} | Retrieving an AccessApproval given its ID. |
POST /accessApproval/group | Retrieving a page of AccessorGroup. This service is only available for ACT. ACT can filter on AccessRequirementId, submitterId, accessorId and expired… |
POST /accessApproval/notifications | Fetches the notifications sent for an access requirement and a list of recipients. This service is only available for ACT. |
PUT /accessApproval/group/revoke | Revoke a group of accessors. Only ACT can perform this action. |
POST /accessApproval/information | Retrieve a batch of AccessApprovalInfo for a single user. |
DELETE /accessApproval | Revoke all Access Approvals an accessor may have for a given Access Requirement. The caller must match the accessorId or the caller must be a member o… |
POST /accessApproval/search | Search through the history of access approvals filtering by accessor/submitter and optional by access requirement id. The caller must be a member of t… |
Access Requirement Services
These services manage the Access Requirements/Restrictions (ARs) which may be placed on Entities, or Teams. An Access Requirement specifies the type of access being restricted as well as how the requirement is fulfilled.
ARs complement Access Control Lists (ACLs) for managing access to Synapse objects. While ACLs are managed by entity owners, ARs are managed by the Synapse Access and Compliance Team (ACT), which is responsible for governance of sensitive data. Before one may access data associated with an AR, there must be a corresponding Access Approval. For certain ARs -- of the "self-sign" variety -- one may grant ones own approval by agreeing to associated 'terms of use.' For other Access Requirements -- of the 'ACT' variety -- approval may be granted only by the ACT.
As stated above, an AR specifies the type of access being controlled. Generally entities are restricted with DOWNLOAD access. A Synapse user may be able to see that a Synapse File exists, but be unable to download the content due to such an AR. Teams are restricted using the PARTICIPATE access type: Prior to joining a Team a user must fulfill any associated ARs controlling this type of access.
Entity ARs are inherited from ancestors. E.g. an AR applied to a Folder will control all Files in the Folder, or within sub-folders of the Folder. Access Requirements are cumulative: A File will be controlled both by ARs applied to it directly and by ARs applied to any and all of its ancestors.
Access Requirements are fulfilled on a per-user basis using the Access Approval Services.
Web Services
Resource | Description |
---|---|
POST /accessRequirement | Add an Access Requirement to an Entity, or Team. This service may only be used by the Synapse Access and Compliance Team. |
GET /accessRequirement/{requirementId} | Get an Access Requirement to an Entity, or Team based on its ID. |
PUT /accessRequirement/{requirementId} | Modify an existing Access Requirement. This service may only be used by the Synapse Access and Compliance Team. |
POST /entity/{id}/lockAccessRequirement | Add a temporary access restriction that prevents access pending review by the Synapse Access and Compliance Team. This service may be used only by an … |
GET /entity/{id}/accessRequirement | Retrieve paginated list of ALL Access Requirements associated with an entity. |
GET /team/{id}/accessRequirement | Retrieve paginated list of ALL Access Requirements associated with a Team. |
DELETE /accessRequirement/{requirementId} | Delete an Access Requirement. This service may only be used by the Synapse Access and Compliance Team. |
PUT /accessRequirement/conversion | Convert an ACTAccessRequirement to a ManagedACTAccessRequirement. Only ACT member can perform this action. |
GET /accessRequirement/{requirementId}/subjects | Retrieve a page of subjects for a given Access Requirement ID. |
GET /accessRequirement/{requirementId}/acl | Fetch the ACL for the access requirement with the given id. |
POST /accessRequirement/{requirementId}/acl | Assign the given ACL to the access requirement with the given id. Only an ACT member is allowed to assign the ACL. Only supports access type. |
PUT /accessRequirement/{requirementId}/acl | Updates the ACL for the access requirement with the given id. Only an ACT member is allowed to update the ACL. Only supports access type. |
DELETE /accessRequirement/{requirementId}/acl | Delete the ACL for the access requirement with the given id. Only an ACT member is allowed to delete the ACL. |
POST /accessRequirement/search | Performs a search through the available access requirements matching the criteria in the given request |
Activity Services
The Activity model represents the main record of Provenance in Synapse. It is analygous to the Activity defined in the W3C Specification on Provenance.
Used & Generated By
Used links are stored directly in the Activity model object as an array of Used objects. There is a flag in Used that marks if it was "executed". Used is an interface that is implemented by two objects:
- UsedEntity - For referencing Entities already stored in Synapse
- UsedURL - For referencing URL-accessed resources stored outside of Synapse. In Provenance visualizations, some URLs are given a special icon, such as links to GitHub. Note: it is also possible to wrap a URL with a FileEntity if you want all the resources that come with Synapse entities.
wasGeneratedBy links are stored for each version of each Entity. Thus you update the entity with the activity id that generated it. You can ask the entity service which activity generated it, and conversely you can ask the activity service what entity versions were generatedBy a given activity.
Access Control for Activities
Access to Activity objects is dictated by the following rules:
- READ - Granted to those users who can see a single Entity that was generated by this Activity.
- UPDATE/DELETE - You must be the creator of the Activity to modify or delete it.
- Setting generatedBy for an Entity (see POST /entity) - You must be the creator of the activity to connect it to an Entity. (The Entity services allow you to specify an activityId that creates a generatedBy relationship between an Activity and an Entity.)
Web Services
Resource | Description |
---|---|
POST /activity | Create a new Activity. If the passed Activity object contains a Used array, you must set the concreteType field of each Used subclass. Access Control:… |
GET /activity/{id} | Get an existing Activity Access Control: Granted to those users who can see a single Entity that was generated by this Activity. |
PUT /activity/{id} | Update an Activity Access Control: You must be the creator of the Activity to modify it. |
DELETE /activity/{id} | Delete an Activity Access Control: You must be the creator of the Activity to delete it. |
GET /activity/{id}/generated | Get the Entities that were generatedBy an Activity. Returns a PaginatedResults of Reference objects. Access Control: This service will return Referenc… |
Agent Chat Services
The Synapse chat services allow the user to chat with a 'bot' (agent) that has access to Synapse data. By default, Synapse provides a 'baseline' agent that has basic access to all of the supported Synapse action group functions and knowledge bases. Sage authorized collaborators can create their own agents that can also utilize the same action groups and knowledge bases used by the baseline agent. The collaborator's agent can then be used to override the baseline agent for chat sessions.
To get started, the first step is to create a new session by calling: POST /agent/session. You will need the sessionId from the resulting AgentSession. The sessionId uniquely identifies a single conversation between the user and the agent. Specifically, the session contains user's chat requests, agent responses and all of the data gathered by the agent to meet user requests. The session data is the context provided to the Large Language Model (LLM) used by the agent. Only the user that create a session will have access to its data and be able to use it for an agent conversation. The user's conversation with an agent is a series of asynchronous jobs under the provided sessionId, where each job is started by providing the user's prompt to the agent. The job's response will then include the agent's response to the user's prompt. Use: POST /agent/chat/async/start to start a chat job and GET /agent/chat/async/get/{asyncToken} to get the job's results.Web Services
Resource | Description |
---|---|
POST /agent/session | Start a new chat session. Each chat session request must include an AgentAccessLevel that defines what level of data access the agent will given durin… |
GET /agent/session/{sessionId} | Get the agent session using its session id. |
PUT /agent/session/{sessionId} | Update the access level of an existing agent session. Only the user that started the session can change its access level. |
POST /agent/chat/async/start | Start an asynchronous job to exchange a single prompt from the user in the request. The agent's response to this prompt can be retrieved by calling: G… |
GET /agent/chat/async/get/{asyncToken} | Get the agent's response to a user's prompt started by calling: POST /agent/chat/async/start Only the user that started the job may get the job's resu… |
POST /agent/chat/trace/{jobId} | Get a single page of trace events associated with an AgentChatRequest. The resulting TraceEvents will be ordered by timestamp ascending. Note: The Age… |
PUT /agent/registration | Create or Get the AgentRegistration that matches the provided request. This call is idempotent. If a matching AgentRegistration already exists, then i… |
GET /agent/registration/{agentRegistrationId} | Get the AgentRegistration given its id. |
Asynchronous Job Services
This is a generic set of services that provides support for both launching asynchronous jobs and monitoring the progress of jobs.
Web Services
Resource | Description |
---|---|
POST /asynchronous/job | This method is used to launch new jobs. The type of job that will be launched is determined by the passed AsynchronousJobBody. The following are the c… |
GET /asynchronous/job/{jobId} | Once a job is launched its progress can be monitored by getting its status with this method. |
Authentication Services
Provides REST APIs for managing and obtaining the necessary credentials to access Synapse.
Authentication to Synapse services requires an access token passed in the HTTP Authorization header, as per the HTTP bearer authorization standard. The access token incorporates a set of 'scopes' and the documentation for each service requiring authorization lists the scopes which the access token must include in order to use that service.
Synapse currently supports four modes of obtaining an access token:
- Present username and password
- Authentication via a whitelisted OAuth 2.0 provider
- Authentication via a registered OAuth 2.0 client
- Exchange an access token for Personal Access Token
The username and password are exchanged for an access token using POST /login2 service. This method should only be used by Synapse itself. No other application should prompt a user for their user name and password.
Synapse allows authentication via a white listed OAuth 2.0 provider. Currently only Google is supported. The final step is POST /oauth2/session2 which returns an access token which is included as a Bearer token in the Authorization header of subsequent requests as described above. Only Synapse itself may use this service, as redirection back from the OAuth2 provider is only allowed to the Synapse web portal.
A registered OAuth 2.0 client can use the OAuth 2.0 services to authenticate, the final step of which is a request to the token endpoint: POST /oauth2/token The returned access token is included as a Bearer token in the Authorization header of subsequent requests as described above.
A user may freely generate up to 100 Personal access tokens (PATs) with scoped access using POST /personalAccessToken. Unlike OAuth access tokens,
- PATs can be freely generated by a user alone and are not linked to any third party OAuth client and
- While ATs have a strict 24 hour lifetime, PATs are long lived, and will only expire if unused for 180 consecutive days
The returned personal access token is included as a Bearer token in the Authorization header of subsequent requests as described above.
Web Services
Resource | Description |
---|---|
POST /login2 | Retrieve an access token that will be usable for 24 hours. The user must accept the terms of use before the access token can be used. |
GET /authenticatedOn | Retrieve the date/time the requesting user was last authenticated, either by presenting their password or by logging in with a recognized identity pro… |
POST /user/password/reset | Sends an email for resetting a user's password. |
POST /user/changePassword | Change the current user's password. This will invalidate existing session tokens. |
POST /termsOfUse2 | Identifies a user by an access token and signs that user's terms of use |
GET /termsOfUse2/info | Get the information about the latest version of the terms of service together with the requirements in effect. |
GET /termsOfUse2/status | |
PUT /termsOfUse2/requirements | Updates the terms of service requirements. Only an administrator can perform this operation. |
GET /secretKey | Retrieves the API key associated with the current authenticated user. |
DELETE /secretKey | Invalidates the API key associated with the current authenticated user. It is not recommended to use this service unless your key has been compromised… |
POST /oauth2/authurl | The first step in OAuth authentication involves sending the user to authenticate on an OAuthProvider's web page. Use this method to get a properly for… |
POST /oauth2/session2 | After a user has been authenticated at an OAuthProvider's web page, the provider will redirect the browser to the provided redirectUrl. The provider w… |
POST /oauth2/alias | After a user has been authenticated at an OAuth provider's web page, the provider will redirect the browser to the provided redirectUrl. The provider … |
POST /oauth2/account2 | After a user has been authenticated at an OAuthProvider's web page, the provider will redirect the browser to the provided redirectUrl. The provider w… |
DELETE /oauth2/alias | Remove an alias associated with an account via the OAuth mechanism. |
POST /personalAccessToken | Issues a personal access token to authorize scoped access to Synapse resources. Note: The scope of the personal access token is the intersection of th… |
GET /personalAccessToken | Retrieve metadata for all personal access tokens issued for the requesting user. Metadata for active and expired tokens will be returned in reverse-ch… |
GET /personalAccessToken/{id} | Retrieve metadata for a particular personal access token. Metadata for revoked tokens cannot be retrieved. |
DELETE /personalAccessToken/{id} | Revoke a personal access token. The token cannot be re-enabled after being revoked. |
DELETE /sessionAccessToken | Revokes the access token used to perform the request. E.g Can be used to logout the current user. |
DELETE /user/{targetUserId}/sessionAccessToken/all | Revokes any access token issued for the given user. If the target user id does not match the user in the access token used to perform the request the … |
Authentication Services (2FA)
APIs to manage two factor authentication (2FA) in Synapse.
Synapse currently supports using authenticator applications that can generate a TOTP that is used as a second factor.To enable 2FA two requests are involved:
- POST /2fa/enroll: Generates a shared secret that is added to the user authenticator application
- POST /2fa: Enables a specific secret generated by 1. to be used as second factor
In order to login through 2FA an additional request needs to be performed after the user attempts to authenticate (e.g. through the POST /login2 API). If the user has 2FA enabled, they will receive a 401 and the body of the response will contain a twoFaToken that can be used in the POST /2fa/token API to obtain an access token.
The user can additionally generate a set of recovery codes using the POST /2fa/recoveryCodes API. The codes are one time use and can be used in place of a TOTP code when performing 2FA authentication. The body of the POST /2fa/token request should specify as otpType RECOVERY_CODE and the value of the otpCode should match one of the generated codes.
Web Services
Resource | Description |
---|---|
POST /2fa/enroll | Initiates the enrollment into two factor authentication. Generates a shared secret that can be used by an authenticator application to generate TOTPs.… |
POST /2fa | Finalize 2FA enrollment, activating the secret associated with the id in the request. This endpoint can be use to replace an existing 2FA secret previ… |
GET /2fa | Fetch the current 2FA status for the user. |
DELETE /2fa | Disable 2FA for the user. |
POST /2fa/token | Performs authentication using 2FA, the body of the request needs to include the twoFaToken received as part of the error when authenticating and the t… |
POST /2fa/recoveryCodes | Generates a new set of single use recovery codes that are associated with the two factor authentication of the user. The recovery codes are single use… |
POST /2fa/reset | Initiates the reset of two factor authentication, sending a notification to the user with a signed token. The request can be performed using the twoFa… |
POST /2fa/disable | Disables two factor authentication for the user encoded in the signed token received by email following a call to the POST /2fa/reset endpoint. The re… |
Certified User Services
To become a Synapse Certified User you must pass a test. The Synapse APIs include a service to provide the test and a service to submit a test result. There are also administrative services to retrieve the history of test submissions.
Web Services
Resource | Description |
---|---|
GET /certifiedUserTest | Get the test to become a Certified User. |
POST /certifiedUserTestResponse | Submit a response to the Certified User test. |
GET /admin/certifiedUserTestResponse | Get the Certified User test responses in the system, optionally filtered by the one who took the test. Note: This service is available to Synapse admi… |
DELETE /admin/certifiedUserTestResponse/{id} | Delete a test response. Note: This service is available to Synapse administrators only. |
GET /user/{id}/certifiedUserPassingRecord | Retrieve the Passing Record on the User Certification test for the given user. |
GET /user/{id}/certifiedUserPassingRecords | Retrieve all the Passing Record on the User Certification test for the given user. Note: This service is available to Synapse administrators only. |
PUT /admin/user/{id}/certificationStatus | Set a user's certification status. For Synapse administrators only. |
PUT /user/{id}/revokeCertification | Revokes the certification for the user. Only an ACT member can perform this operation. |
Challenge Services
A Challenge is a special object that supplements a project, providing additional features specific to challenges. This set of services provides "CRUD" for Challenge objects and ChallengeTeam objects, which register a Team for a Challenge. The services also provide a number of queries regarding Challenges, challenge participants and challenge Teams.
Web Services
Resource | Description |
---|---|
POST /challenge | Create a Challenge object, associated with a Project. A participant Team must be specified. To create a Challenge one must have CREATE permission on t… |
GET /challenge/{challengeId} | Retrieve a Challenge given its ID. To retrieve a Challenge one must have READ permission on the associated Project. |
GET /entity/{id}/challenge | Retrieve a Challenge given the ID of its associated Project. To retrieve a Challenge one must have READ permission on the Project. |
GET /challenge | List the Challenges for which the given participant is registered. To be in the returned list the caller must have READ permission on the project asso… |
PUT /challenge/{challengeId} | Update a Challenge. The caller must have UPDATE permission on the project associated with the Challenge. It is not permitted to change the project ass… |
DELETE /challenge/{challengeId} | Delete a Challenge. The caller must have DELETE permission on the project associated with the Challenge. |
GET /challenge/{challengeId}/participant | List the participants registered for a Challenge. The caller must have READ permission on the project associated with the Challenge. |
POST /challenge/{challengeId}/challengeTeam | Register a Team with a Challenge. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) and… |
GET /challenge/{challengeId}/challengeTeam | List the Teams registered for a Challenge. You must have READ permission in the associated Project to make this request. |
GET /challenge/{challengeId}/registratableTeam | List the Teams that caller can register for the Challenge, i.e. Teams on which the caller is an administrator and which are not already registered. Th… |
PUT /challenge/{challengeId}/challengeTeam/{challengeTeamId} | Update a Challenge Team. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) and be an ad… |
DELETE /challengeTeam/{challengeTeamId} | De-register a Team from a Challenge. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) … |
GET /challenge/{challengeId}/submissionTeams | List the Teams under which the given submitter may submit to the Challenge, i.e. the Teams on which the user is a member and which are registered for … |
DOI Services
Provides REST APIs for managing Synapse DOIs.
Web Services
Resource | Description |
---|---|
GET /doi | Retrieves the DOI for the object and its associated DOI metadata. Note: this call calls an external API, which may impact performance To just retrieve… |
GET /doi/association | Retrieves the DOI for the object. Note: this call only retrieves the DOI association, if it exists. To retrieve the metadata for the object, see GET /… |
POST /doi/async/start | Asynchronously creates or updates a DOI in Synapse, with input metadata. Retrieve the results with GET /doi/async/get/{asyncToken}. This call may fail… |
GET /doi/async/get/{asyncToken} | Get the results of a call to POST /doi/async/start |
GET /doi/locate | Retrieves the Synapse web portal URL to the object entered. Note: This call does not check to see if the object exists in Synapse. |
Data Access Services
Some data in Synapse are governed by an ACTAccessRequirement. To gain access to these data, a user must meet all requirements specified in the ACTAccessRequirement.
These services provide the APIs for users to create request to gain access to controlled data, and APIs for the ACT to review and grant access to users.
Web Services
Resource | Description |
---|---|
POST /researchProject | Create a new ResearchProject or update an existing ResearchProject. |
GET /accessRequirement/{requirementId}/researchProjectForUpdate | Retrieve an existing ResearchProject that the user owns. If none exists, a ResearchProject with some re-filled information is returned to the user. On… |
POST /dataAccessRequest | Create a new Request or update an existing Request. |
GET /accessRequirement/{requirementId}/dataAccessRequestForUpdate | Retrieve the Request for update. If one does not exist, an Request with some re-filled information is returned. If a submission associated with the re… |
POST /dataAccessRequest/{requestId}/submission | Submit a Submission using information from a Request. |
PUT /dataAccessSubmission/{submissionId}/cancellation | Cancel a submission. Only the user who created this submission can cancel it. |
PUT /dataAccessSubmission/{submissionId} | Request to update a submission' state. Only ACT member can perform this action. |
POST /accessRequirement/{requirementId}/submissions | Retrieve a list of submissions for a given access requirement ID. Allows to optionally filter by submission state and/or id of an accessor setting the… |
DELETE /dataAccessSubmission/{submissionId} | Delete a submission. Only an ACT member can perform this action. |
POST /accessRequirement/{requirementId}/approvedSubmissionInfo | Return the research project info for approved data access submissions, ordered by submission modified-on date, descending. Note that accessor changes … |
GET /accessRequirement/{requirementId}/status | Retrieve an access requirement status for a given access requirement ID. |
POST /restrictionInformation | Retrieve restriction information on a restrictable object |
POST /restrictionInformation/batch | Retrieve restriction information on a batch of restrictable object, limited to a maxiumum of 50 object ids |
GET /dataAccessSubmission/openSubmissions | Retrieve information about submitted Submissions. Only ACT member can perform this action. |
POST /dataAccessSubmission/search | Performs a search through access submissions that are reviewable by the user and that match the criteria in the given request. An ACT user can see all… |
GET /dataAccessSubmission/{submissionId} | Fetch a submission by its id. If the user is a not part of the ACT they must be validated and assigned as reviewers of the AR submissions in order to … |
Discussion Services
Discussions in Synapse are captured in the Project's Forum. Each Project has a Forum. Each Forum has a set of Moderators. The Moderators manage the content of the Forum.
A Forum has multiple Threads. A Thread is created by an authorized user. Other authorized users can view and reply to an existing Thread.
These services provide the APIs for Moderators and authorized users to create, edit, and manage the conversations that happen in Synapse.
Web Services
Resource | Description |
---|---|
GET /project/{projectId}/forum | This API is used to get the Forum's metadata for a given project ID. Target users: anyone who has READ permission to the project. |
GET /forum/{forumId} | This API is used to get the Forum's metadata for a given its ID. Target users: anyone who has READ permission to the project. |
GET /forum/{forumId}/threads | This API is used to get N number of threads for a given forum ID. Target users: anyone who has READ permission to the project. |
POST /thread | This API is used to create a new thread in a forum. Target users: anyone who has READ permission to the project. |
GET /thread/{threadId} | This API is used to get a thread and its statistic given its ID. Target users: anyone who has READ permission to the project. |
PUT /thread/{threadId}/title | This API is used to update the title of a thread. Target users: only the author of the thread can update its title. |
PUT /thread/{threadId}/message | This API is used to update the message of a thread. Target users: only the author of the thread can update its message. |
DELETE /thread/{threadId} | This API is used to mark a thread as deleted. Target users: only forum's moderator can mark a thread as deleted. |
PUT /thread/{threadId}/restore | This API is used to restore a deleted thread. Target users: only forum's moderator can restore a deleted thread. |
PUT /thread/{threadId}/pin | This API is used to mark a thread as pinned. Target users: only forum's moderator can mark a thread as pinned. |
PUT /thread/{threadId}/unpin | This API is used to unpin a thread. Target users: only forum's moderator can unpin a thread. |
GET /thread/messageUrl | This API is used to get the message URL of a thread. The message URL is the URL to download the file which contains the thread message. Target users: … |
POST /reply | This API is used to create a new reply to a thread. Target users: anyone who has READ permission to the project. |
GET /reply/{replyId} | This API is used to get a reply and its statistic given its ID. Target users: anyone who has READ permission to the project. |
PUT /reply/{replyId}/message | This API is used to update the message of a reply. Target users: only the author of the reply can update its message. |
DELETE /reply/{replyId} | This API is used to mark a reply as deleted. Target users: only forum's moderator can mark a reply as deleted. |
GET /thread/{threadId}/replies | This API is used to get N number of replies for a given thread ID. Target users: anyone who has READ permission to the project. |
GET /reply/messageUrl | This API is used to get the message URL of a reply. The message URL is the URL to download the file which contains the reply message. Target users: an… |
GET /forum/{forumId}/threadcount | This API is used to get the total number of threads for a given forum ID. Target users: anyone who has READ permission to the project. |
GET /thread/{threadId}/replycount | This API is used to get the total number of replies for a given thread ID. Target users: anyone who has READ permission to the project. |
GET /entity/{id}/threads | This API is used to get N number of threads that belongs to projects user can view and references the given entity. Target users: anyone who has READ … |
POST /entity/threadcounts | This API is used to get list of entity and count pairs, with count is the number of threads that belong to projects user can view and references the g… |
GET /forum/{forumId}/moderators | Returns a page of moderators for a given forum ID. Target users: anyone who has READ permission to the project. |
POST /forum/{forumId}/search | Performs a full text search in the forum defined by the given id. Target users: anyone who has READ permission on the project of the forum. |
Docker Authorization Services
These services allow Synapse to act as an authorization service for a Docker Registry. For more details see: https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md Authorization is either:
- User name and password, included in the request as a Basic Authorization header
- An oauth access token, passed as a Bearer Authorization header. To execute 'docker pull' the access token must include 'download' scope; to execute 'docker push' the access token must include 'modify' scope and should include 'download' scope.
Web Services
Resource | Description |
---|---|
GET /bearerToken | Authorize Docker operation. This service is called by the Docker client only and is not for general use. |
Docker Commit Services
These services relate to the 'commits' to Docker repositories. Note that create, update and delete of the Docker repositories themselves are done using the Entity Services, for external/unmanaged repositories, or by direct integration with the Docker registry, for managed Docker repositories. Tagged commits for both managed and external/unmanaged repositories may be retrieved using the 'listDockerTags' API included in this service.
Web Services
Resource | Description |
---|---|
POST /entity/{id}/dockerCommit | Add a commit (tag and digest) for an external/unmanaged Docker repository. (Commits for managed repositories are added via direct integration with the… |
GET /entity/{id}/dockerTag | List the tagged commits (tag/digest pairs) for the given Docker repository. Only the most recent digest for each tag is returned since, following Dock… |
Docker Registry Event Services
These services process events from the Docker Registry. They are separated from other Docker Controllers because the authorization is different, i.e. basic authorization using a key/value pair. These services are not intended to be used by Synapse clients, only by the Docker registry.
Web Services
Resource | Description |
---|---|
POST /events | Post a list of Docker registry events (pushes and pulls). Synapse will process accordingly. The main purpose is to create managed Docker repositories … |
Download List Services
Services for managing a user's download list.
Files can be added to the user's download list using POST /download/list/add. Files can be removed from the user's download by calling either POST /download/list/remove, or the entire list can be cleared with: DELETE /download/list. In order to query the files on a user's download list, first start an asynchronous job using POST /download/list/query/async/start to get an asynchToken. The job results can be monitored using GET /download/list/query/async/get/{asyncToken}. While the job is still processing the GET call will return a status code of 202 (ACCEPTED). Once the job is complete the GET call will return a status code of 200 with the response body. Download List Service Limitsresource | limit | notes |
---|---|---|
Maximum number of files on a user's download list | 100,000 files | |
Maximum batch size for adding/removing files | 1000 files |
Web Services
Resource | Description |
---|---|
POST /download/list/add | A request to add a batch of files to the user’s download list. Authentication is required. A user can only access their own download list. |
POST /download/list/remove | A request to remove a batch of files from the user's download list. Authentication is required. A user can only access their own download list. |
DELETE /download/list | Clear all files from the user's download list. Authentication is required. A user can only access their own download list. |
POST /download/list/query/async/start | Start an asynchronous job to query the user's download list. This call will return an asyncToken that can be used to monitor the job by calling GET /d… |
GET /download/list/query/async/get/{asyncToken} | Get the results of an asynchronous job to query the user's download list. Started with POST /download/list/query/async/start. While the job is still p… |
POST /download/list/add/async/start | Start an asynchronous job to add files to a user's download list from either a view query or a folder. Use GET /download/list/add/async/get/{asyncToke… |
GET /download/list/add/async/get/{asyncToken} | Get the results of an asynchronous job to add files to a user's download list started with: POST /download/list/add/async/start Note: When the result … |
POST /download/list/package/async/start | Start an asynchronous job to create a zip package of files from a user's download list. After files are added to the a zip package they will be remove… |
GET /download/list/package/async/get/{asyncToken} | Get the results of an asynchronous job to package files from a user's download list started with: POST /download/list/package/async/start. The respons… |
POST /download/list/manifest/async/start | Start an asynchronous job to generate a metadata manifest CSV of the available files on the use’s download list. Use GET /download/list/manifest/async… |
GET /download/list/manifest/async/get/{asyncToken} | Get the results of an asynchronous job to generate a metadata manifest CSV of the available files from the user's download list download list started … |
Drs Services
The Data Repository Service API provides access to data objects in single, standard way regardless of where they are stored and how they are managed. The data objects for which information can be fetched are FileEntity and Dataset.The data object that is downloaded is a file.
The supported end points for DRS are:
Use the GET /service-info API to get information about GA4GH-compliant web services, including DRS services, to be aggregated into registries and made available via a standard API.
Use the GET /objects/{object_id} API to get information about individual DRS objects.Web Services
Resource | Description |
---|---|
GET /service-info | The service information API will provide information regarding supported GA4GH services. Checkout the drs specification for GA4GH Service Registry |
GET /objects/{object_id} | The DRSObject API will provide information about a DrsObject, which can be a FileEntity or Dataset. The DrsObject is fetched by its drsId i.e., its Sy… |
GET /objects/{object_id}/access/{access_id} | This API will provide the url from which a FileEntity may be downloaded. If the file is stored in AWS S3 or a GCP bucket then the result is a time lim… |
Entity Bundle Services V2
The Entity Bundle Services provide bundled access to Entities and their related data components. An EntityBundle can be used to create, fetch, or update an Entity and associated objects with a single web service request.
Web Services
Resource | Description |
---|---|
POST /entity/{id}/bundle2 | Get an entity and related data with a single POST. |
POST /entity/{id}/version/{versionNumber}/bundle2 | Get an entity at a specific version and its related data with a single POST. |
POST /entity/bundle2/create | Create an entity and associated components with a single POST. Specifically, this operation supports creation of an Entity, its Annotations, and its A… |
PUT /entity/{id}/bundle2 | Update an entity and associated components with a single PUT. Specifically, this operation supports update of an Entity, its Annotations, and its ACL.… |
Entity Services
All data in Synapse is organize into Projects. These Projects can be further organized into hierarchical Folders. Finally, the data is then represented by FileEntities that reside within Folders or directly within Projects. All these objects (Projects, Folders, FileEntities) are derived from a common object called Entity. The Entity Services provide the means to create, read, update, and delete Synapse Entities. There are also services for navigating the Entity hierarchies , setting Authorization rules, and Annotating Entities.
In addition to the basic entity types (Project, Folder, & FileEntity), Synapse also supports the following Entity types:
- TableEntity
- DockerRepository
- EntityView
- SubmissionView
- Dataset
- DatasetCollection
- MaterializedView
- VirtualTable
The following methods provide the basic Create, Read, Update, Delete (CRUD) for Entities:
Annotations
An Entity can be annotated using the PUT /entity/{id}/annotations2 method. Each annotation is a key-value pair. The GET /entity/{id}/annotations2 method can be used to get the current annotations of an entity.
Authorization
An Entity's authorization is controlled by the Entity's Access Control List (ACL). When a new Project is created a new ACL is automatically created for the Project. New Folders and FileEnties start off inheriting the ACL of their containing Project. This means they do not have their own ACL and all authorization is controlled by their Project's ACL. The term 'benefactor' is used to indicate which Entity an Entity inherits its ACL from. For example, a newly created Project will be its own benefactor, while a new FileEntity's benefactor will start off as its containing Project. The current benefactor of any Entity can be determined using the GET /entity/{id}/benefactor method.
For the case where a Folder or FileEntity needs its own ACL (as opposed to inheriting it from its containing Project) a new ACL can be created for the Entity using the POST /entity/{id}/acl method. When a new ACL is created for an Entity it will no longer inherit its permission from its containing Project and it will become its own benefactor.
While creating or updating an ACL, only Certified Users can add DOWNLOAD permission for Authenticated Users group.
For the case where a Folder or FileEntity no longer needs its own ACL, the ACL can deleted using the DELETE /entity/{id}/acl method. When the ACL of an File or Folder is deleted, it will automatically be assigned the same benefactor as its parent Entity. Deleting the ACL of a Project is not allowed.
The GET /entity/{id}/acl can be used to get an Entity's ACL.
To determine what permissions a User has on an Entity, the GET /entity/{id}/permissions method should be used.
In addition to authorization via ACLs, entities may be restricted via AccessRequirements (ARs). For more information, see Access Requirement Services and Access Approval Services
Versions
Currently, FileEntities are "versionable" meaning it is possible for it to have multiple versions of the file. Whenever, a FileEntity is updated with a new FileHandle whose MD5 differs from the MD5 of the current file hanlde a new version of the FileEntity is automatically created. The history of a FileEntity can be retrieved using GET /entity/{id}/version method. A specific version of a FileEntity can be retrieved using GET /entity/{id}/version/{versionNumber} method. The Annotations of a specific version of an FileEntity can be retrieved using the GET /entity/{id}/version/{versionNumber}/annotations method.
Despite being versionable, Tables, Views and Materialized Views are versioned using snapshots: see POST /entity/{id}/table/snapshot and POST /entity/{id}/table/transaction/async/start.
Note: Only the File and Annotations of an Entity are included in the version. All other components of an Entity such as description, name, parent, ACL, and WikiPage are not not part of the version, and will not vary from version to version.
JSON Schemas
Each Entity type and Model object in Synapse is defined by a JSON schema. The GET /REST/resources method will list the full name of all Resources used by Synapse. The schema for each Resource is accessible via GET /REST/resources/schema. Note: Many of these resources are composition objects and one must navigate various interfaces of an object to fully digest it. Therefore, a flattened (or effective) schema for each resource is available from the GET /REST/resources/effectiveSchema
Entity Service Limitsresource | limit |
---|---|
Maximum size of an Entity.name | 256 characters |
Maximum size of an Entity.desciption | 1000 characters |
Maximum number of versions for a single Entity | 15,000 |
Maximum number of keys in Annotations | 100 |
Maximum number of values associated with a single key in Annotations | 100 |
Maximum total character count for all values associated with a single key in Annotations when the AnnotationValueType is STRING | 500 |
Maximum hierarchical depth of an Entity | 50 |
Web Services
Resource | Description |
---|---|
POST /entity | Create a new Entity. This method is used to create Projects, Folders, File Entities, etc. The passed request body should contain the following fields:… |
GET /entity/{id} | Get an Entity using its ID. Note: To get an Entity the caller must be granted the ACCESS_TYPE.READ on the Entity. |
PUT /entity/{id} | Update an entity. If the Entity is a FileEntity and the dataFileHandleId fields is set to a new value, then a new version will automatically be create… |
PUT /entity/{id}/version/{versionNumber}/filehandle | Updates the FileHandle associated with the FileEntity with the provided entity id and version. |
DELETE /entity/{id} | Moves an entity in the trash can, if the skipTrashCan is set to true will flag the entity for purge and it will be deleted as soon as possible. Note: … |
GET /entity/{id}/annotations2 | Get the annotations for an entity. Note: The caller must be granted the ACCESS_TYPE.READ on the Entity, to get its annotations. |
GET /entity/{id}/version/{versionNumber}/annotations2 | Get an Entity's annotations for a specific version of a FileEntity. |
PUT /entity/{id}/annotations2 | Update an Entity's annotations. Note: The caller must be granted the ACCESS_TYPE.UPDATE on the Entity, to update its annotations. |
DELETE /entity/{id}/version/{versionNumber} | Delete a specific version of a FileEntity. |
GET /entity/{id}/version/{versionNumber} | Get a specific version of an Entity. Note: Only the current version of the Entity can be used for an Entity update. Therefore, only the current versio… |
GET /entity/{id}/type | Get the EntityHeader of an Entity given its ID. The EntityHeader is a light weight object with basic information about an Entity includes its type. |
GET /entity/type | Get a batch of EntityHeader given multile Entity IDs. The EntityHeader is a light weight object with basic information about an Entity includes its ty… |
POST /entity/header | Get the EntityHeader for a list of references with a POST. If any item in the batch fails (e.g., with a 404) it will be EXCLUDED in the result set. |
GET /entity/{id}/permissions | Get the list of permission that the caller has on a given Entity. A User's permission on an Entity is a calculation based several factors including th… |
GET /entity/{id}/access | Determine if the caller have a given permission on a given Entity. A User's permission on an Entity is a calculation based several factors including t… |
GET /entity/{id}/actions/download | Returns the list of actions required by the user to gain access to the given entity for download. |
GET /entity/{id}/path | Get the full path of an Entity as a List of EntityHeaders. The first EntityHeader will be the Root Entity, and the last EntityHeader will be the reque… |
POST /entity/{id}/acl | Create a new Access Control List (ACL), overriding inheritance. By default, Entities such as FileEntity and Folder inherit their permission from their… |
GET /entity/{id}/acl | Get the Access Control List (ACL) for a given entity. Note: If this method is called on an Entity that is inheriting its permission from another Entit… |
PUT /entity/{id}/acl | Update an Entity's ACL. Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to call this method. |
DELETE /entity/{id}/acl | Delete the Access Control List (ACL) for a given Entity. By default, Entities such as FileEntity and Folder inherit their permission from their contai… |
GET /entity/{id}/benefactor | Get an Entity's benefactor. The term 'benefactor' is used indicate which Entity an Entity inherits is ACL from. For example, a newly created Project w… |
GET /entity/{id}/version | Get all versions of an Entity one page at a time. |
GET /REST/resources | Get the list of Resource names for all Resources of Synapse. This includes The full names of each Entity type and Model object of the API. The resulti… |
GET /REST/resources/effectiveSchema | Get the effective schema of a resource using its name. Many of the Synapse resource are composition objects and one must navigate various interfaces o… |
GET /REST/resources/schema | Get the full schema of a REST resource. Many of the Synapse resource are composition objects and the various interfaces must be navigated to fully dig… |
GET /entity/{id}/generatedBy | Get an existing activity for the current version of an Entity. |
GET /entity/{id}/version/{versionNumber}/generatedBy | Get an existing activity for a specific version of an Entity. |
PUT /entity/{id}/generatedBy | Sets the generatedBy relationship for the current version of an Entity. |
DELETE /entity/{id}/generatedBy | Deletes the generatedBy relationship for the current version of an Entity. |
GET /entity/{id}/filepreview | Get the URL of the preview file associated with the current version of a FileEntity. Note: This call will result in a HTTP temporary redirect (307), t… |
GET /entity/{id}/version/{versionNumber}/filepreview | Get the URL of the preview file associated with a specific version of a FileEntity. Note: This call will result in a HTTP temporary redirect (307), to… |
GET /entity/{id}/filehandles | Get the FileHandles of the file currently associated with the current version of the Entity If a preview exists for the file then the handle of the pr… |
GET /entity/{id}/version/{versionNumber}/filehandles | Get the FileHandles of the file associated with a specific version of a FileEntity. If a preview exists for the file then the handle of the preview an… |
GET /entity/md5/{md5} | Gets at most 200 FileEntities matching the given MD5 string which the user has read access to. NOTE: Another option is to create a file view that incl… |
GET /entity/alias/{alias} | Lookup an Entity ID using an alias. |
GET /entity/dockerRepo/id | For managed docker repositories find the entity id matching the given repository name |
POST /entity/children | Get a page of children for a given parent ID. This service can also be used to list projects by setting the parentId to NULL in EntityChildrenRequest.… |
POST /entity/child | Retrieve an entityId for a given parent ID and entity name. This service can also be used to lookup projectId by setting the parentId to NULL in Entit… |
PUT /entity/{id}/datatype | Change the DataType of the given entity. The entity's DataType controls how the entity can be accessed. For example, an entity's DataType must be set … |
GET /entity/{id}/sts | Gets the temporary S3 credentials from STS for the given entity. These credentials are only good for the bucket and base key specified by the returned… |
PUT /entity/{id}/schema/binding | Bind a JSON schema to an Entity. The bound schema will be used to validate the Entity's metadata (annotations). Any child Entity that does not have a … |
GET /entity/{id}/schema/binding | Get information about a JSON schema bound to an Entity. Note: Any child Entity that does not have a bound schema will inherit the first bound schema f… |
DELETE /entity/{id}/schema/binding | Clear the bound JSON schema from this Entity. The schema will no longer be used to validate this Entity or its children. Note: The caller must be gran… |
GET /entity/{id}/json | Get the raw JSON for the given entity. The resulting JSON can be used for the validation of a entity against a JsonSchema. Note: The caller must be gr… |
GET /entity/{id}/version/{versionNumber}/json | Get the raw JSON for the given entity and version. The resulting JSON can be used for the validation of an entity against a JsonSchema. Note: The call… |
PUT /entity/{id}/json | Update the annotations of an entity using the raw JSON of the entity. See: GET entity/{id}/json to get the JSON of an entity. Note: The caller must be… |
GET /entity/{id}/schema/validation | Get the validation results of an Entity against its bound JSON schema. The validation of an Entity against its bound schema is automatic and eventuall… |
GET /entity/{id}/schema/validation/statistics | Get the The summary statistics of the JSON schema validation results for a single container Entity such as a Project or Folder. Only direct children o… |
POST /entity/{id}/schema/validation/invalid | Get a single page of invalid JSON schema validation results for a container Entity (Project or Folder). The validation of an Entity against its bound … |
GET /entity/{id}/derivedKeys | If the given Entity has derived annotations, then this will return the distinct annotation keys of those annotations. If they entity does not have der… |
Evaluation Services
The Evaluation API is designed to support open-access data analysis and modeling challenges in Synapse. This framework provides tools for administrators to collect and analyze data models from Synapse users created for a specific goal or purpose.
The data model of the Evaluation API is built around around two primary objects:
- Evaluation: The primary object representing a Synapse Evaluation. Access to Evaluations is governed by an Access Control List (ACL).
- Submission: A user in a Synapse Evaluation can submit a Synapse Entity as Submission to that Evaluation. Submission data is owned by the parent Evaluation, and is immutable.
The data model includes additional objects to support scoring of Submissions and convenient data access:
- SubmissionStatus: An object used to track scoring information for a single Submission. This object is intended to be modified by the users (or test harnesses) managing the Evaluation.
- SubmissionBundle: A convenience object to transport a Submission and its accompanying SubmissionStatus in a single web service call.
- SubmissionView: A submission view can be created using the Entity Services providing as scope a list of evaluation ids, in order to query the set of submissions through the Table Query Services. Annotations set in the submissionAnnotations property of a SubmissionStatus can be exposed in the view.
Web Services
Resource | Description |
---|---|
POST /evaluation | Creates a new Evaluation. The passed request body should contain the following fields: name - Give your new Evaluation a name. contentSource - The ID … |
GET /evaluation/{evalId} | Gets an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation. |
GET /entity/{id}/evaluation | Gets Evaluations tied to a project. Note: The response will contain only those Evaluations on which the caller is granted the ACCESS_TYPE.READ permiss… |
GET /evaluation | Gets a collection of Evaluations, within a given range. Note: The response will contain only those Evaluations on which the caller is granted the ACCE… |
GET /evaluation/available | Gets a collection of Evaluations in which the user has SUBMIT permission, within a given range. Note: The response will contain only those Evaluations… |
GET /evaluation/name/{name} | Finds an Evaluation by name. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation. |
PUT /evaluation/{evalId} | Updates an Evaluation. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time an Evaluation is updated… |
DELETE /evaluation/{evalId} | Deletes an Evaluation. Note: The caller must be granted the ACCESS_TYPE.DELETE on the specified Evaluation. |
GET /evaluation/{evalId}/team/{id}/submissionEligibility | Find out whether a Team and its members are eligible to submit to a given Evaluation queue (at the current time). The request must include an Evaluati… |
POST /evaluation/submission | Creates a Submission and sends a submission notification email to the submitter's team members. The passed request body should contain the following f… |
POST /admin/evaluation/submission/{subId}/contributor | Add a contributor to an existing Submission. This service is available to administrators only. |
GET /evaluation/submission/{subId} | Gets a Submission. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Evaluation. |
GET /evaluation/submission/{subId}/status | Gets the SubmissionStatus object associated with a specified Submission. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evalua… |
PUT /evaluation/submission/{subId}/status | Updates a SubmissionStatus object. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time an Submissio… |
PUT /evaluation/{evalId}/statusBatch | Update multiple SubmissionStatuses. The maximum batch size is 500. To allow upload of more than this maximum, the system supports uploading of a serie… |
DELETE /evaluation/submission/{subId} | Deletes a Submission and its accompanying SubmissionStatus. Note: The caller must be granted the ACCESS_TYPE.DELETE_SUBMISSION on the specified Evalua… |
GET /evaluation/{evalId}/submission/all | Gets a collection of Submissions to a specified Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified … |
GET /evaluation/{evalId}/submission/status/all | Gets a collection of SubmissionStatuses to a specified Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation. … |
GET /evaluation/{evalId}/submission/bundle/all | Gets a collection of bundled Submissions and SubmissionStatuses to a given Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_S… |
GET /evaluation/{evalId}/submission | Gets the requesting user's Submissions to a specified Evaluation. |
GET /evaluation/{evalId}/submission/bundle | Gets the requesting user's bundled Submissions and SubmissionStatuses to a specified Evaluation. |
GET /evaluation/submission/{subId}/file/{fileHandleId} | Gets a pre-signed URL to access a requested File contained within a specified Submission. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVAT… |
GET /evaluation/{evalId}/submission/count | Gets the number of Submissions to a specified Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Ev… |
GET /evaluation/{evalId}/access | Determines whether a specified Synapse user has a certain ACCESS_TYPE on the specified Evaluation. |
PUT /evaluation/acl | Updates the supplied access control list (ACL) for an evaluation. The ACL to be updated should have the ID of the evaluation. The user should have the… |
GET /evaluation/{evalId}/acl | Gets the access control list (ACL) governing the given evaluation. The user should have the proper permissions to read the ACL. |
GET /evaluation/{evalId}/permissions | Gets the user permissions for the specified evaluation. |
PUT /evaluation/submission/{subId}/cancellation | User requests to cancel their submission. Only the user who submitted a submission can make this request. |
POST /evaluation/{evalId}/round | Creates a new EvaluationRound to associate with a Evaluation. You must have UPDATE permissions for the associated Evaluation in order to create an Eva… |
GET /evaluation/{evalId}/round/{roundId} | Retrieve an existing EvaluationRound associated with a Evaluation. You must have READ permissions for the associated Evaluation in order to retrieve a… |
POST /evaluation/{evalId}/round/list | Retrieve all EvaluationRounds associated with a Evaluation. You must have READ permissions for the associated Evaluation in order to retrieve all Eval… |
PUT /evaluation/{evalId}/round/{roundId} | Update an existing EvaluationRound to associate with a Evaluation. You must have UPDATE permissions for the associated Evaluation in order to update a… |
DELETE /evaluation/{evalId}/round/{roundId} | Delete an existing EvaluationRound to associate with a Evaluation. You must have UPDATE permissions for the associated Evaluation in order to delete a… |
POST /evaluation/{evalId}/migratequota | Migrates the DEPRECATED SubmissionQuota in the "quota" field of an Evaluation into one or many EvaluationRound (depending on the "numberOfRounds" defi… |
File Services
A FileHandle is an abstraction for a reference to a file in Synapse. For details on the various types see: FileHandle.
Multi-part File Upload API
In order to ensure file upload is robust, all files must be uploaded to Synapse in 'parts'. This means clients are expected to divide each file into 'parts' and upload each part separately. Since Synapse tracks the state of all multi-part uploads, upload failure can be recovered simply by uploading all parts that Synapse reports as missing.
Note: For multi-part upload 1 MB is defined as 1024*1024 bytes
The first task in multi-part upload is choosing a part size. The minimum part size is 5 MB (1024*1024*5) and the maximum part size is 5 GB (1024*1024*1024*5). Therefore, any file with a size less than or equal to 5 MB will have a single part and a partSize=5242880. The maximum number of parts for a single file 10,000 parts. The following should be used to choose a part size:
partSize = max(5242880, (fileSize/10000))
Once a partSize is chosen, a multi-part upload can be started using the following: POST /file/multipart which will return an MultipartUploadStatus. The client is expected to use MultipartUploadStatus to drive the upload. The client will need to upload each missing part (parts with '0' in the partsState) as follows:
- Get a pre-signed URL to upload the part to using: POST /file/multipart/{uploadId}/presigned/url/batch
- Upload the part to the pre-signed URL using HTTPs PUT
- Add the part to the multi-part upload using: PUT /file/multipart/{uploadId}/add/{partNumber}
Once all parts have been successfully added to the multi-part upload, the upload can be completed using: PUT /file/multipart/{uploadId}/complete to produce a new FileHandle If the upload fails for any reason, the client should start over ( POST /file/multipart) and continue by uploading any parts that are reported as missing.
Multi-part File Copy API
The multipart API supports a robust copy of existing files to other locations (e.g. in case of a data migration) without the need to download and re-upload the file. This is currently supported only from and to S3 storage locations that reside in the same region. In order to initiate a multipart copy, a POST /file/multipart request can be sent using as the body of the request a MultipartUploadCopyRequest.
The part size allows to parallelize the copy in multiple sub-parts, the same limits of the upload applies to the copy (e.g. it is possible to copy a file in a single part up to 5 GB). When initiating a copy we recommend to choose the part size as follows:
partSize = max(104857600, (fileSize/10000))
Once the multipart copy is initiated the process is the same as the multipart upload:
- Get the part copy pre-signed URLs using: POST /file/multipart/{uploadId}/presigned/url/batch
- For each pre-signed URL perform an HTTP PUT request with no body, the response of the previous endpoint contains a map of headers that are signed with the URL, all of the headers MUST be included in the PUT request.
- Once the copy request is performed, add the part to the multi-part copy using: PUT /file/multipart/{uploadId}/add/{partNumber}. The value of the partMD5Hex parameter will be MD5 checksum returned in the response of the request sent to the pre-signed URL.
- Once all parts have been successfully added to the multi-part copy, the copy can be completed using: PUT /file/multipart/{uploadId}/complete to produce a new FileHandle
Note about the copy integrity: The resulting file handle will have the same content MD5 of the source file handle, but synapse does not try to re-compute or verify this value. Instead, the integrity check is performed by the cloud provider (currently only S3) during the copy request for the part (the request sent to the pre-signed URL). Each copy pre-signed URL is signed with a special header that makes sure that the source file didn't change during the copy, if this is the case the PUT request to the pre-signed URL will fail and a new copy should be re-started.
Associating FileHandles with Synapse objects
FileHandles can be associated with various type of objects such as a FileEntity and WikiPage. The full list of association types can be found in the FileHandleAssociateType enumeration.
Note that a file handle MUST always be associated with an object, if a file handle is not associated with an objects for more than 30 days Synapse will mark it as UNLINKED and eventually archive or delete it from the system.
For more information see the following:
- FileEntity
- POST /entity
- PUT /entity/{id}
- GET /entity/{id}/filepreview
- GET /entity/{id}/version/{versionNumber}/filepreview
- GET /entity/{id}/filehandles
- GET /entity/{id}/version/{versionNumber}/filehandles
- POST /fileHandle/batch
resource | limit | notes |
---|---|---|
Minimum file size | 0 bytes | |
Maximum file size | 5 TB (5,497,558,100,000 bytes) | |
Maximum number of parts | 10,000 | Minimum file part size | 5 MB (5,242,880 bytes) | The recommended part size for an upload is max(5242880, (fileSize/10000)). For a copy max(104857600, (fileSize/10000)). |
Maximum file part size | 5 GB (5,368,709,120 bytes) |
Web Services
Resource | Description |
---|---|
POST /fileHandle/batch | Get a batch of pre-signed URLs and/or FileHandles for the given list of FileHandleAssociations |
POST /fileHandle/{handleIdToCopyFrom}/copy | Create a copy of an S3FileHandle with a new name and/or content type |
GET /fileHandle/{handleId} | Get a FileHandle using its ID. Note: Only the user that created the FileHandle can access it directly. |
DELETE /fileHandle/{handleId} | Delete a FileHandle using its ID. Note: Only the user that created the FileHandle can delete it. Also, a FileHandle cannot be deleted if it is associa… |
DELETE /fileHandle/{handleId}/filepreview | Delete the preview associated with the given FileHandle. This will cause Synapse to automatically generate a new preview. |
POST /externalFileHandle | Create an ExternalFileHandle to represent an external URL. Synapse will attempt to generate a preview for any external URL that can be publicly read. … |
POST /externalFileHandle/s3 | Create an S3FileHandle to represent an S3Object in a user's S3 bucket. In order to use this method an ExternalS3StorageLocationSetting must first be c… |
POST /externalFileHandle/googleCloud | Create an GoogleCloudFileHandle to represent a Google Cloud Blob in a user's Google Cloud bucket. In order to use this method an ExternalGoogleCloudSt… |
GET /entity/{id}/uploadDestinationLocations | Get the upload destination locations available for this parent entity. This will return a list of at least one destination location. The first destina… |
GET /entity/{id}/uploadDestination/{storageLocationId} | Get the upload destination associated with the given storage location id. This will always return an upload destination |
GET /entity/{id}/uploadDestination | Get the default upload destination for the entity with the given id. The id might refer to the parent container (e.g. a folder or a project) where a f… |
GET /fileHandle/{handleId}/url | Get a URL that can be used to download a file of a FileHandle. Note: This call will result in a HTTP temporary redirect (307), to the actual file URL … |
POST /file/bulk/async/start | Start an asynchronous job to download multiple files in bulk. This job will generate a zip file that contains each requested file that the caller is a… |
GET /file/bulk/async/get/{asyncToken} | Get the results of a bulk file download started with POST /file/bulk/async/start Note: When the result is not ready yet, this method will return a sta… |
GET /file/{id} | Get the actual URL of the file from with an associated object . Note: This call will result in a HTTP temporary redirect (307), to the actual file URL… |
POST /file/multipart | Start or resume a multi-part upload or copy of a file. By default this method is idempotent, so subsequent calls will simply return the current status… |
POST /file/multipart/{uploadId}/presigned/url/batch | Get a batch of pre-signed URLS that should be used to upload or copy file parts. Each part will require a unique pre-signed URL. For an upload the cli… |
PUT /file/multipart/{uploadId}/add/{partNumber} | After the contents of part have been uploaded or copied with the PUT to the part pre-signed URL this service is used to confirm the addition of the pa… |
PUT /file/multipart/{uploadId}/complete | After all of the parts have been upload and added successfully, this service is called to complete the upload resulting in the creation of a new file … |
POST /filehandles/copy | Copy a batch of FileHandles. This API will check for DOWNLOAD permission on each FileHandle. If the user has DOWNLOAD permission on a FileHandle, we w… |
POST /download/list/add/async/start | Start an asynchronous job to add files to a user's download list. Note: There is a limit of 100 files on a user's download list. Use GET /download/lis… |
GET /download/list/add/async/get/{asyncToken} | Get the results of an asynchronous job to add files to a user's download list started with: POST /download/list/add/async/start Note: When the result … |
POST /download/list/add | Add the given list of FileHandleAssociations to the caller's download list. Note: There is a limit of 100 files on a user's download list. |
POST /download/list/remove | Remove the given list of FileHandleAssociations to the caller's download list. |
DELETE /download/list | Clear the caller's download list. |
GET /download/list | Get the user's current download list. |
POST /download/order | Create a download Order from the user's current download list. Only files that the user has permission to download will be added to the download order… |
GET /download/order/{orderId} | Get a download order given its orderId. Only the user that created the order can get it. |
POST /download/order/history | Get the caller's download order history in reverse chronological order. This is a paginated call. |
POST /fileHandle/restore/async/start | Starts an asynchronous job to restore a batch of file handles that were ARCHIVED or UNLINKED. The file handles status will be set as AVAILABLE. Note t… |
GET /fileHandle/restore/async/get/{asyncToken} | Get the results of an asynchronous job to restore a batch of files handles started with: POST /fileHandle/restore/async/start. The response includes f… |
Form Services
Collection of APIs from managing and submitting form data. There are two basic objects:
- FormData - Represent an end user's data gathered from a form template. All FormData belongs to a single FormGroup.
- FormGroup - Represents a grouping of FormData with an Access Control List (ACL) for administration. The ACL controls both who can submit data to the group and who has access to the submitted data.
To download the data associated with a FormData object use: POST /fileHandle/batch providing the formData.dataFileHandleId with FileHandleAssociateType.FormData
Web Services
Resource | Description |
---|---|
POST /form/group | Create a FormGroup with the provided name. This method is idempotent. If a group with the provided name already exists and the caller has ACCESS_TYPE.… |
GET /form/group/{id} | Get a FormGroup with the provided ID. Note: The caller must have the ACCESS_TYPE.READ permission on the identified group. |
GET /form/group/{id}/acl | Get the Access Control List (ACL) for a FormGroup. Note: The caller must have the ACCESS_TYPE.READ permission on the identified group. |
PUT /form/group/{id}/acl | Update the Access Control List (ACL) for a FormGroup. The following define the permissions in this context: READ - Grants read access to the group. RE… |
POST /form/data | Create a new FormData object. The caller will own the resulting object and will have access to read, update, and delete the FormData object. Note: The… |
PUT /form/data/{id} | Update an existing FormData object. The caller must be the creator of the FormData object. Once a FormData object has been submitted, it cannot be upd… |
DELETE /form/data/{id} | Delete an existing FormData object. The caller must be the creator of the FormData object. Note: Cannot delete a FormData object once it has been subm… |
POST /form/data/{id}/submit | Submit the identified FormData from review. Note: The caller must have the SUBMIT permission on the identified group to update the group's ACL. |
POST /form/data/list | List FormData objects and their associated status that match the filters of the provided request that are owned by the caller. Note: Only objects owne… |
POST /form/data/list/reviewer | List FormData objects and their associated status that match the filters of the provided request for the entire group. This is used by service account… |
PUT /form/data/{id}/accept | Called by the form reviewing service to accept a submitted data. Note: The caller must have the READ_PRIVATE_SUBMISSION permission on the identified g… |
PUT /form/data/{id}/reject | Called by the form reviewing service to reject a submitted data. Note: The caller must have the READ_PRIVATE_SUBMISSION permission on the identified g… |
JSON Schema Services
This set of services provide project designers with tools to define their own schemas to control and validate metadata applied to Projects, Folders, and Files. All schemas are defined using JSON schemas following json-schema.org specification.
To get started, you will need to either create a new Organization or join an existing Organization. Each Organization has an AccessControlList (ACL) that controls which users/teams are authorized to contribute schemas under that Organization's name-space. The Organization's name-space is referenced using the Organization's name, which is also the root of all schema $ids within the Organization.
Web Services
Resource | Description |
---|---|
POST /schema/organization | Create a new Organization by providing a unique organization name. The new Organization will have an auto-generated AcessControlList (ACL) granting th… |
GET /schema/organization | Lookup an Organization by name. |
POST /schema/organization/list | List all organizations. Each call will return a single page of Organizations. Forward the provided nextPageToken to get the next page. |
DELETE /schema/organization/{id} | Delete the identified Organization. All schemas defined within the Organization's name-space must first be deleted before an Organization can be delet… |
GET /schema/organization/{id}/acl | Get the AcessControlList (ACL) associated with the identified Organization. Note: The caller must be granted the ACCESS_TYPE.READ permission to get an… |
PUT /schema/organization/{id}/acl | Update the AccessControlList (ACL) for the identified Organization. Note: The caller must be granted the ACCESS_TYPE.CHANGE_PERMISSIONS permission to … |
POST /schema/type/create/async/start | Start an asynchronous job to create a new JSON schema. A JSON schema must include an $id that is a relative URL of that schema. The pseudo-BNF syntax … |
GET /schema/type/create/async/get/{asyncToken} | Get the results of an asynchronous job that was started to create a new JSON schema. * Note: If the job has not completed, this method will return a s… |
GET /schema/type/registered/{id} | Get a registered JSON schema using its $id. |
POST /schema/list | List all JSON schemas for an Organization. Each call will return a single page of schemas. Forward the provided nextPageToken to get the next page. |
POST /schema/version/list | List the version information for each version of a given schema. Each call will return a single page of results. Forward the provide nextPageToken to … |
DELETE /schema/type/registered/{id} | Delete the given schema using its $id. If the $id excludes a semantic version, all versions of the schema will be deleted. If the $id includes a seman… |
POST /schema/type/validation/async/start | To use a JSON schema for validation, the JSON schema plus all of its dependency schemas must be provided to a JSON schema validator. The 'validation' … |
GET /schema/type/validation/async/get/{asyncToken} | Get the results of an asynchronous job that was started to compile a 'validation' schema for a JSON schema. Note: If the job has not completed, this m… |
Log Service
https://sagebionetworks.jira.com/wiki/display/PLFM/Repository+Service+API#RepositoryServiceAPI-QueryAPI
Web Services
Resource | Description |
---|---|
POST /log | Logs the entry in the Synapse service logs. Clients can use this to log errors that the service should know about. |
Membership Invitation Services
The Membership Invitation Services create, retrieve and delete membership invitations. A membership invitation is created by a Team administrator to invite a Synapse user to join the Team. Without the invitation it is not possible for an outside user to join. For more on Teams, see Team Services.
Web Services
Resource | Description |
---|---|
POST /membershipInvitation | Create a membership invitation and send an email notification to the invitee. The team must be specified. Also, either an inviteeId or an inviteeEmail… |
GET /user/{id}/openInvitation | Retrieve the open invitations to a user, optionally filtering by the Team of origin. An invitation is only open if it has not expired and if the user … |
GET /team/{id}/openInvitation | Retrieve the open invitations from a Team, optionally filtering by the invitee. An invitation is only open if it has not expired and if the user has n… |
GET /membershipInvitation/{id} | Retrieve an invitation by ID Note: The client must be an administrator of the Team referenced by the invitation or the invitee to make this request. |
POST /membershipInvitation/{id} | Retrieve an invitation by ID using a MembershipInvtnSignedToken for authorization |
DELETE /membershipInvitation/{id} | Delete an invitation Note: The client must be an administrator of the Team referenced by the invitation or the invitee to make this request. |
GET /membershipInvitation/openInvitationCount | Retrieve the number of pending Membership Invitations |
GET /membershipInvitation/{id}/inviteeVerificationSignedToken | Verify whether the inviteeEmail of the indicated MembershipInvitation is associated with the authenticated user. If it is, the response body will cont… |
PUT /membershipInvitation/{id}/inviteeId | Set the inviteeId of a MembershipInvitation. A valid InviteeVerificationSignedToken must have an inviteeId equal to the id of the authenticated user a… |
Membership Request Services
The Membership Request Services create, retrieve and delete membership requests. A membership request is created by a Synapse user to request admission to a Team. Without the request it is not possible for a Team to admit the user. For more on Teams, see Team Services.
Web Services
Resource | Description |
---|---|
POST /membershipRequest | Create a membership request and send an email notification to the administrators of the team. The Team must be specified. Optionally, the creator may … |
GET /team/{id}/openRequest | Retrieve the open requests submitted to a Team, optionally filtering by the requester. An request is only open if it has not expired and if the reques… |
GET /user/{id}/openRequest | Retrieve the open requests submitted by a user, optionally filtering by the Team. An request is only open if it has not expired and if the requester h… |
GET /membershipRequest/{id} | Retrieve an request by ID Note: The client must be the creator of the membership request to make this request. |
DELETE /membershipRequest/{id} | Delete a request Note: The client must be the creator of the membership request to make this request. |
GET /membershipRequest/openRequestCount | Retrieve the number of pending Membership Requests for teams that user is admin |
Message Services
Provides REST APIs for sending messages to other Synapse users and for commenting on Synapse entities.
Web Services
Resource | Description |
---|---|
POST /message | Sends a message. The "fileHandleId" field should point to a plain text file containing the body of the message. The file should be uploaded prior to t… |
POST /cloudMailInMessage | Note: This service is designed to be used by CloudMailIn, not by clients in general. Calling the service requires Basic Authentication credentials own… |
POST /cloudMailInAuthorization | Note: This service is designed to be used by CloudMailIn, not by clients in general. |
GET /message/inbox | Retrieves the current authenticated user's inbox. It may take several seconds for a message to appear in the inbox after creation. By default, the mos… |
GET /message/outbox | Retrieves the current authenticated user's outbox. By default, the most recent messages are returned first. To flip the ordering, set the "descending"… |
GET /message/{messageId} | Fetches the specified message. The authenticated user must be either the sender or receiver of the message. |
POST /message/{messageId}/forward | Forwards a message to the specified set of recipients. The authenticated user must be either the sender or receiver of the forwarded message. |
GET /message/{messageId}/conversation | Retrieves messages belonging to the same thread as the given message. The current authenticated user will be either the sender or receiver of all retu… |
PUT /message/status | Updates the current status of a message relative to the current authenticated user. Note: the "recipientId" field of the request body will be ignored.… |
DELETE /admin/message/{messageId} | Deletes a message. Only accessible to administrators. |
GET /message/{messageId}/file | Get the actual URL of the file associated with the message Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if t… |
POST /entity/{id}/message | Adds the owner of the given entity as an additional recipient of the message. Afterwards, behavior is identical to POST /message |
OpenID Connect Services
The OpenID Connect (OIDC) services implement OAuth 2.0 with the OpenID identity extensions.
Web Services
Resource | Description |
---|---|
GET /.well-known/openid-configuration | Get the Open ID Configuration ("Discovery Document") for the Synapse OIDC service. |
GET /oauth2/jwks | Get the JSON Web Key Set for the Synapse OIDC service. This is the set of public keys used to verify signed JSON Web tokens generated by Synapse. |
POST /oauth2/client | Create an OAuth 2.0 client. Note: The client name must be unique. Note: After creating the client one must also set the client secret and have their c… |
POST /oauth2/client/secret/{id} | Get a secret credential to use when requesting an access token. See the Open ID Connect specification for client authentication Synapse supports 'clie… |
GET /oauth2/client/{id} | Get an existing OAuth 2.0 client. When retrieving one's own client, all metadata is returned. It is permissible to retrieve a client anonymously or as… |
GET /oauth2/client | List the OAuth 2.0 clients created by the current user. |
PUT /oauth2/client/{id}/verificationPrecheck | Check whether the proposed change to an OAuth Client will cause the client to enter the 'unverified' state. This service also validates the submitted … |
PUT /oauth2/client/{id} | Update the metadata for an existing OAuth 2.0 client. Note: Only the creator of a client can update it. Note: Changing the redirect URIs and/or the se… |
DELETE /oauth2/client/{id} | Delete OAuth 2.0 client |
POST /oauth2/description | Get a user-readable description of the authentication request. This request does not need to be authenticated. |
POST /oauth2/consentcheck | Check whether user has already granted consent for the given OAuth client, scope, and claims. Consent persists for one year. |
POST /oauth2/consent | Get authorization code for a given client, scopes, response type(s), and extra claim(s). See: Open ID Connect specification for consent. Open ID Conne… |
POST /oauth2/token | Get access, refresh and id tokens, as per the Open ID Connect specification for the token request. Request must include client ID and Secret in Basic … |
GET /oauth2/userinfo | The result is either a JSON Object or a JSON Web Token, depending on whether the client registered a signing algorithm in its userinfo_signed_response… |
POST /oauth2/userinfo | The result is either a JSON Object or a JSON Web Token, depending on whether the client registered a signing algorithm in its userinfo_signed_response… |
GET /oauth2/audit/grantedClients | Get a paginated list of the OAuth 2 clients that currently have active refresh tokens that grant access to the user's Synapse identity and/or resource… |
GET /oauth2/audit/grantedClients/{clientId}/tokens | Get a paginated list of metadata about refresh tokens granted to a particular OAuth 2 client on behalf of the requesting user. The token itself may no… |
GET /oauth2/audit/tokens/{tokenId}/metadata | Retrieve the metadata for an OAuth 2.0 refresh token as an authenticated Synapse user. Clients that wish to retrieve OAuth 2.0 refresh token metadata … |
GET /oauth2/token/{tokenId}/metadata | Retrieve the metadata for an OAuth 2.0 refresh token. The request should be made as an OAuth 2.0 client using basic authentication. Users that wish to… |
PUT /oauth2/audit/tokens/{tokenId}/metadata | Update the metadata for a refresh token. At this time, the only field that a user may set is the 'name' field. |
POST /oauth2/audit/grantedClients/{clientId}/revoke | Revoke all refresh tokens and their related access tokens associated with a particular client and the requesting user. Note that access tokens that ar… |
POST /oauth2/audit/tokens/{tokenId}/revoke | Revoke a particular refresh token and all of its related access tokens using its unique ID. The caller must be the the user/resource owner associated … |
POST /oauth2/revoke | Revoke a particular refresh token using the token itself, or an associated access token. The caller must be the the client associated with the refresh… |
Principal Services
A Principal in Synapse can be a User, Group, or a Team. This is a set of services that provides the means to look-up principals by their various attributes and also to test unique names such as USER_NAME, USER_EMAIL, or TEAM_NAME are available for use.
Web Services
Resource | Description |
---|---|
POST /principal/available | This call is used to determine if an alias is currently available. Authentication is not required for this call. Each value of each AliasType must hav… |
POST /account/emailValidation | This service starts the process of creating a new account by sending a 'validation email' message to the provided email address. The email contains a … |
POST /account2 | This service completes the email validation process for setting up a new account. The client must provide the validation token which was sent by email… |
POST /account/{id}/emailValidation | This service starts the process of adding a new email address to an existing account by sending a 'validation email' message to the provided email add… |
POST /email | This service completes the email validation process for adding a new email address to an existing account. The client must provide the validation toke… |
DELETE /email | This service removes an email address from an account. The request is rejected if the email address is not currently owned by the user or if the email… |
PUT /notificationEmail | This service sets the email used for user notifications, i.e. when a Synapse message is sent and if the user has elected to receive messages by email,… |
GET /notificationEmail | This service returns the email used for user notifications, i.e. when a Synapse message is sent and if the user has elected to receive messages by ema… |
POST /principal/alias | Lookup a principal ID using an alias and alias type. |
Project Settings Services
The project settings services provide configuration options that can be applied to projects. In particular through the POST /projectSettings and PUT /projectSettings services a user can create or update the setting of a specific type for a project.
Currently supported settings for a project are:- UploadDestinationListSetting: Used to customize the storage location for files in a project
Web Services
Resource | Description |
---|---|
GET /projectSettings/{id} | Gets the ProjectSetting with the given id. Note that this is not the id of a project, in order to retrieve the project settings by the project id plea… |
GET /projectSettings/{projectId}/type/{type} | Gets the ProjectSetting of a particular type for the project with the given id. Currently supported types: upload: Used to retrieve the UploadDestinat… |
POST /projectSettings | Create a ProjectSetting for a project. The setting may be any of the implementations of ProjectSetting. Only the users with CREATE access to the proje… |
PUT /projectSettings | Update an existing ProjectSetting. Only the users with UPDATE access to the project can update a project setting. Currently supports: UploadDestinatio… |
DELETE /projectSettings/{id} | Deletes a ProjectSetting. Only the users with DELETE access to the project can delete a project setting. |
POST /storageLocation | Creates a StorageLocationSetting, which can be associated with a project for users to upload their data to a user-owned location. The request object s… |
GET /storageLocation/{id} | Get the StorageLocationSetting with the given id. Only the creator of the StorageLocationSetting can retrieve it by its id. |
Recycle Bin Services
The recycle bin (or trash can) is the special folder that holds the deleted entities for users.
Services are provided for users to delete entities into the trash can, to view entities in the trash can, to purge entities from the trash can, and to restore entities out of the trash can.
Web Services
Resource | Description |
---|---|
PUT /trashcan/trash/{id} | Moves an entity and its descendants to the trash can. |
PUT /trashcan/restore/{id} | Moves an entity and its descendants out of the trash can back to its original parent. An exception is thrown if the original parent does not exist any… |
PUT /trashcan/restore/{id}/{parentId} | Moves an entity and its descendants out of the trash can to a new parent. NOTE: This operation cannot be completed if the original parent has been del… |
GET /trashcan/view | Retrieves the paginated list of trash entities deleted by the current user. |
PUT /trashcan/purge/{id} | Flags the specified entity for priority purge. The entity will be deleted as soon as possible. Once purging is done, the entity will be permanently de… |
Search Services
Search for Entities on Synapse
Web Services
Resource | Description |
---|---|
POST /search | Searches for Entitys that are accessible by the current user. If not authenticated, only public result will be shown. See SearchFieldName for the list… |
Statistics Services
Services that expose statistics computed by the backend.
Web Services
Resource | Description |
---|---|
POST /statistics | Generic endpoint to retrieve statistics about objects. The user should have READ access on the object referenced by the objectId in the request. Curre… |
Storage Report Services
Provides REST APIs for generating Storage Reports. These may only be used by the Synapse Report Team.
Web Services
Resource | Description |
---|---|
POST /storageReport/async/start | Asynchronously creates a report detailing the usage of Synapse storage with project-level resolution. Retrieve the results with GET /storageReport/asy… |
GET /storageReport/async/get/{asyncToken} | Get the results of a call to POST /storageReport/async/start |
Subscription Services
While working in Synapse, users may want to subscribe to different topics to receive notifications about changes in those topics.
These services provide the APIs for Synapse users to manage their subscriptions.
Web Services
Resource | Description |
---|---|
POST /subscription | This API is used to subscribe to a topic. Target users: anyone who has READ permission on the object. |
POST /subscription/all | This API is used to subscribe to all topic of the same SubscriptionObjectType. Only the following SubscriptionObjectType are allowed in this API: DATA… |
POST /subscription/list | This API is used to retrieve subscriptions one has based on a list of provided topics. These topics must have the same objectType. Target users: all S… |
GET /subscription/{id} | This API is used to retrieve a subscription given its ID Target users: Synapse user who created this subscription. |
GET /subscription/all | This API is used to retrieve all subscriptions one has. Target users: all Synapse users. |
DELETE /subscription/{id} | This API is used to unsubscribe to a topic. Target users: Synapse user who created this subscription. |
DELETE /subscription/all | This API is used to unsubscribe all topics one followed. Target users: Synapse users |
POST /subscription/subscribers | Retrieve subscribers for a given topic. |
POST /subscription/subscribers/count | Retrieve number of subscribers for a given topic. |
Table Services
A Synapse TableEntity model object represents the metadata of a table. Each TableEntity is defined by a list of ColumnModel IDs. Use POST /column to create new ColumnModel objects. Each ColumnModel object is immutable, so to change a column of a table a new column must be added and the old column must be removed. TableEntities can be created, updated, read and deleted like any other entity:
All ColumnModel objects are publicly viewable and usable. Since each ColumnModel is immutable it is safe to re-use ColumnModels created by other users. Use the GET /column services to list all of the existing ColumnModels that are currently in use.
Once the columns for a TableEntity have been created and assigned to the TableEntity, rows can be added to the table using POST /entity/{id}/table/transaction/async/start. Each Row appended to the table will automatically be assigned a rowId and a versionNumber and can be found in the resulting RowReferenceSet. To update a row, simply include the row's rowId in the passed RowSet. Any row without a rowId will be treated as a new row. When a row is updated a new versionNumber will automatically be assigned the Row. While previous versions of any row are kept, only the current version of any row will appear in the table index used to support the query service: POST /entity/{id}/table/query/async/startUse the POST /entity/{id}/table/query/async/start services to query for the current rows of a table. The returned RowSet of the table query can be modified and returned to update the rows of a table using POST /entity/{id}/table/transaction/async/start.
There is also an asynchronous service to upload and download csv files, suitable for large datasets.
Table Service Limits
resource | limit | notes |
---|---|---|
Maximum size of column names | 256 characters | |
Maximum number of enumeration values for a single column | 100 | |
Maximum number of columns per table/view | 152 | |
The maximum possible width of a table/view | 64 KB | Each ColumnType has a maximum possible size. The total width of a table/view is the sum of the maximum size of each of its columns |
The maximum number of LARG_TEXT columns per table/view | 30 | Maximum table size | ~146 GB | All row changes applied to a table are automatically batched into changes sets with a maximum size of 5242880 bytes (5 MB). Currently, there is a limit of 30,000 change sets per table. Therefore, the theoretical maximum size of table is 5242880 bytes * 30,000 = ~ 146 GB. |
The maximum number of projects/folder per view scope | 30 K | Recursive sub-folders count towards this limit. For example, if a project contains more than 30 K sub-folders then it cannot be included in a view's scope. |
The maximum number of rows per view | 200 M | A single folder cannot contain more then 10 K files/folders. Since a view's scope is limited to 30 K project/folders, the maximum number of rows per view is 10 K * 30 K = 300 M. |
The maximum file size of a CSV that can be appended to a table | 1 GB | |
The maximum size of a single query result | 512000 bytes | |
Entity View only: The maximum total character length for a STRING or STRING_LIST ColumnType | 500 characters | Entity Views ONLY! This follows limitations placed on Annotations. For the type STRING_LIST, the total character count is the cumulative length of all string contained in the list. |
Entity View only: The maximum list length for "_LIST" suffixed ColumnType | 100 values | Entity Views ONLY! This follows limitations placed on Annotations. |
Web Services
Resource | Description |
---|---|
POST /column | Create a ColumnModel that can be used as a column of a TableEntity. Unlike other objects in Synapse ColumnModels are immutable and reusable and do not… |
POST /column/batch | Create a batch of ColumnModel that can be used as columns of a TableEntity. Unlike other objects in Synapse ColumnModels are immutable and reusable an… |
GET /column/{columnId} | Get a ColumnModel using its ID. |
GET /entity/{id}/column | Given the ID of a TableEntity, get its list of ColumnModels that are currently assigned to the table. Service Limits resource limit The maximum freque… |
GET /column | List all of the ColumnModels that have been created in Synapse. Since each ColumnModel is immutable it is safe to re-use ColumnModels created by other… |
GET /column/tableview/defaults | Get the list of default ColumnModels for the given viewEntityType and viewTypeMask. |
POST /entity/{id}/table/transaction/async/start | Start a table update job that will attempt to make all of the requested changes in a single transaction. All updates will either succeed or fail as a … |
GET /entity/{id}/table/transaction/async/get/{asyncToken} | Asynchronously get the results of a table update transaction started with POST /entity/{id}/table/transaction/async/start Note: When the result is not… |
POST /entity/{id}/table/filehandles | This method is used to get file handle information for rows in a TableEntity. The columns in the passed in RowReferenceSet need to be FILEHANDLEID col… |
GET /entity/{id}/table/column/{columnId}/row/{rowId}/version/{versionNumber}/file | Get the actual URL of the file associated with a specific version of a row and file handle column. Note: This call will result in a HTTP temporary red… |
GET /entity/{id}/table/column/{columnId}/row/{rowId}/version/{versionNumber}/filepreview | Get the preview URL of the file associated with a specific version of a row and file handle column. Note: This call will result in a HTTP temporary re… |
POST /entity/{id}/table/query/async/start | Asynchronously start a query. Use the returned job id and GET /entity/{id}/table/query/async/get to get the results of the query Using a 'SQL like' sy… |
GET /entity/{id}/table/query/async/get/{asyncToken} | Asynchronously get the results of a query started with POST /entity/{id}/table/query/async/start. Note: When the result is not ready yet, this method … |
POST /entity/{id}/table/download/csv/async/start | Asynchronously start a csv download. Use the returned job id and GET /entity/{id}/table/download/csv/async/get to get the results of the query |
GET /entity/{id}/table/download/csv/async/get/{asyncToken} | Asynchronously get the results of a csv download started with POST /entity/{id}/table/download/csv/async/start Note: When the result is not ready yet,… |
POST /table/upload/csv/preview/async/start | The method can be used to test both the parameters for reading an upload CSV file and the required table schema. The caller can then adjust both param… |
GET /table/upload/csv/preview/async/get/{asyncToken} | Asynchronously get the results of a csv upload preview started with POST /table/upload/csv/async/start Note: When the result is not ready yet, this me… |
POST /entity/{id}/table/upload/csv/async/start | Asynchronously start a csv upload. Use the returned job id and GET /entity/{id}/table/upload/csv/async/get to get the results of the query Service Lim… |
GET /entity/{id}/table/upload/csv/async/get/{asyncToken} | Asynchronously get the results of a csv upload started with POST /entity/{id}/table/upload/csv/async/start Note: When the result is not ready yet, thi… |
POST /column/view/scope/async/start | Starts an asynchronous job to compute a page of the possible ColumnModels based on the annotations within the provided scope. The result of the job ca… |
GET /column/view/scope/async/get/{asyncToken} | Fetches the result of the POST /column/view/scope/async/start service that'll contain a page of possible ColumnModels within the scope supplied in the… |
POST /entity/{id}/table/snapshot | Request to create a new snapshot of a table. The provided comment, label, and activity ID will be applied to the current version thereby creating a sn… |
POST /validateDefiningSql | Validate the potential definingSQL for a view before the creation of the view. |
Team Services
Teams are groups of users. Teams can be granted access permissions to projects, folders and files, and share other resources by adding them to Access Control Lists (ACLs). Any authenticated Synapse user may create a Team, for which they become an administrator. Team administrators may:
- invite other users to join the Team,
- accept membership requests from users wishing to join the Team,
- grant or revoke administrative control to Team members,
- remove a user from the Team.
Other Synapse users may:
- issue membership requests to a Team,
- accept Team membership invitations (join the Team),
- unilaterally choose to leave a Team once added.
Web Services
Resource | Description |
---|---|
POST /team | Create a new Team. The passed request body may contain the following fields: name - Give your new Team a name. The name must be unique, not used by an… |
GET /teams | Retrieve a paginated list of Teams matching the supplied name fragment (optional), in alphabetical order by Team name. Note: This service has JSONP su… |
GET /user/{id}/team | Retrieve a paginated list of Teams to which the given user belongs. |
GET /user/{id}/team/id | Retrieve a paginated list of IDs of Teams to which the given user belongs. If sorting is desired, both sort and ascending must be specified. If they a… |
POST /teamList | Retrieve a list of Teams given their IDs. Invalid IDs in the list are ignored: The results list is simply smaller than the list of IDs passed in. |
GET /team/{id}/member/{principalId} | Service Limits resource limit The maximum frequency this method can be called 1 calls per second |
GET /team/{id} | Retrieve the metadata for a specified Team. Service Limits resource limit The maximum frequency this method can be called 1 calls per second |
GET /team/{id}/icon | Retrieve the download URL for the Team icon, or receive a redirect response to said URL. |
GET /team/{id}/icon/preview | Retrieve the download URL for the Team icon preview, or receive a redirect response to said URL. |
PUT /team | Update the Team metadata for the specified Team. Note: The client must be a Team administrator to make this request. |
DELETE /team/{id} | Delete the Team. Note: The client must be a Team administrator to make this request. |
PUT /team/{id}/member/{principalId} | Add a member to the Team. If the one making the request is the user to be added, then the user must have an open invitation from the Team. If the one … |
PUT /teamMember | Add a member to the Team. Note: The request is authenticated by a hash message authentication code in the request body, generated by Synapse. The inte… |
GET /team/{id}/member/{principalId}/membershipStatus | Retrieve the Team Membership Status bundle for a team and user. This says whether a user is a member of a Team, whether there are outstanding membersh… |
GET /teamMembers/{id} | Retrieve a paginated list of Team members matching the supplied name prefix. If the prefix is omitted then all members are returned. Note: This servic… |
GET /teamMembers/count/{id} | Retrieve the number of Team members matching the supplied name prefix. If the prefix is omitted then the number of members in the team is returned. No… |
POST /team/{id}/memberList | Returns the TeamMember info for a team and a given list of members' principal IDs. Invalid IDs in the list are ignored: The results list is simply sma… |
POST /user/{id}/memberList | Returns the TeamMember info for a user and a given list of Team IDs. Not Found status is returned if the user ID is invalid, any of the Team IDs are i… |
DELETE /team/{id}/member/{principalId} | Remove the given member from the specified Team. Note: The client must either be a Team administrator or the member being removed. |
GET /team/{id}/acl | Retrieve the AccessControlList for a specified Team. |
PUT /team/acl | Update the Access Control List for the specified Team. |
User & Group Services
Web Services
Resource | Description |
---|---|
GET /userGroup | Get the user-groups in the system |
User Profile Services
Every Synapse user has an associated UserProfile.
Web Services
Resource | Description |
---|---|
GET /userProfile | Get the profile of the caller (my profile). Note: Private user profile fields will be returned. |
GET /user/bundle | Get the user bundle of the caller (my own bundle). Note: Private fields will be returned. |
GET /userProfile/{profileId} | Get the profile of a specified user. Note: Private fields (e.g. "rStudioUrl") are omitted unless the requester is the profile owner or an administrato… |
GET /user/{id}/bundle | Get the user bundle of a specified user. Note: Private fields (e.g. "rStudioUrl") are omitted unless the requester is the profile owner or an administ… |
GET /user | Get all publicly available UserProfile data in the system |
PUT /userProfile | Update your own profile Note: The user associated with the UserProfile "ownerId" must match the identity of the caller, otherwise an Unauthorized resp… |
PUT /notificationSettings | Update email notification settings. Note: The request is authenticated by a hash message authentication code, generated by Synapse. The intended use o… |
GET /userGroupHeaders/batch | Batch get UserGroupHeaders. This fetches information about a collection of users or groups, specified by Synapse IDs. |
POST /userProfile | Batch get UserGroupHeaders. This fetches information about a collection of users or groups, specified by Synapse IDs. |
GET /userGroupHeaders | Get Users and Groups that match the given prefix. |
POST /userGroupHeaders/aliases | Get Users and Groups that match the given list of aliases. |
GET /userProfile/{profileId}/image | Get the actual URL of the image file associated with a user's profile. Note: This call will result in a HTTP temporary redirect (307), to the actual f… |
GET /userProfile/{profileId}/image/preview | Get the actual URL of the image file associated with a user's profile. Note: This call will result in a HTTP temporary redirect (307), to the actual f… |
POST /favorite/{id} | Add an Entity as a Favorite of the caller. |
DELETE /favorite/{id} | Remove an Entity as a Favorite of the caller. |
GET /favorite | Get a paginated result that contains the caller's Favorites |
GET /projects | Get a paginated result that contains project headers and user activity (last access date) of the caller. The project list includes only those for whic… |
GET /projects/user/{principalId} | Get a paginated result that contains project headers and user activity (last access date) of the user specified by 'principalId'. The project list inc… |
Verification Services
Identity verification is a service offered by the Synapse Access and Compliance Team to add an additional layer of legitimacy to a user account, beyond the basic requirements for creating an account in Synapse. After completing their user profile a user may submit a verification request, including supporting documentation. The ACT reviews the information then approves or rejects it. After approval, the ACT retains the authority to suspend verification of an account previously verified. Once rejected or suspended a user may create a new verification request.
Web Services
Resource | Description |
---|---|
POST /verificationSubmission | Create a VerficationSubmission. The content must match that of the user's profile. Notification is the request is sent to the Synapse Access and Compl… |
POST /verificationSubmission/{id}/state | Update the state of a verification submission. The allowed transitions are: Submitted -> Approved Submitted -> Rejected Approved -> Suspended Notifica… |
DELETE /verificationSubmission/{id} | Delete a verification submission by its ID. Note: This service may be called only by the original verification requestor. |
GET /verificationSubmission | List the verification submissions in the system. This service is available only to the Synapse Access and Compliance Team. Submissions may be filtered… |
Webhook Services
Provides APIs to manage webhooks that are triggered by synapse events.
A webhook can specify the id of a synapse entity to receive events for. For entities that represent a container (folder and project), matching events are published to the webhook endpoint for any entity in their hierarchy.
Before events are published to the endpoint, the webhook needs to be verified. A special request is sent to the webhook endpoint containing a verification code that can be submitted in the body of the POST /webhook/{webhookId}/verify request.
Request Format
There are two types of requests that can be sent to an endpoint:- WebhookVerificationMessage: Sent when a webhook is created or when its endpoint is updated that contains the verification code used to verify the webhook.
- WebhookSynapseEventMessage: Sent when a synapse event that match the webhook entity is generated in the backend.
- X-Syn-Webhook-Id: The id of the webhook
- X-Syn-Webhook-Message-Type: The type of message body, either Verification or SynapseEvent
- X-Syn-Webhook-Message-Id: A unique id for the message
- X-Syn-Webhook-Owner-Id: The id of the user that created the webhook
- Content-Type: Always application/json
- User-Agent: Set with the prefix Synapse-Webhook/, followed by the synapse stack version
- Authorization: Set with the Bearer prefix, followed by an authentication token (See below)
Request Handling
A request to an endpoint is sent at least once and retried for a maximum of 3 times. The endpoint needs to provide a response within 2 seconds in order for the request to be considered successful, otherwise the request is retried. Valid HTTP response codes are:- 200 (OK)
- 201 (CREATED)
- 202 (ACCEPTED)
- 204 (NO CONTENT)
- 429 (TOO MANY REQUESTS)
- 500 (INTERNAL SERVER ERROR)
- 502 (BAD GATEWAY)
- 503 (SERVICE UNAVAILABLE)
- 504 (GATEWAY TIMEOUT)
Limits
Each user is limited to a maximum of 25 webhooks. The webhook endpoint is checked against a white list of allowed domain patterns, currently only the AWS Api Gateway execute-api is allowed. For adding a new domain exception you can submit a request to the Synapse Service Desk.Authentication
By default each request includes a signed JSON Web Token (JWT) in the Authorization header as a bearer token. The token is signed with a JSON Web Key (JWK) and can be verified using the public JWK id specified in the header of the JWT. The public keys are published under the "well-known" discovery document of the issuer (See below).The JWT will contain a set of standard claims that can be used to validate the token:
- iss: The issuer of the token is set to https://repo-prod.prod.sagebase.org/auth/v1. The openid discovery document (https://repo-prod.prod.sagebase.org/auth/v1/.well-known/openid-configuration) can be used to get information about the JWKs
- aud: The audience contains the id of the user that owns the webhook
- iat: The timestamp when the token was generated
- exp: The expiration time of the token, each token is valid for 30 seconds.
Web Services
Resource | Description |
---|---|
POST /webhook | Create a new webhook. A user can create a maximum of 25 webhooks. Once created the webhook needs to be verified using the POST /webhook/{webhookId}/ve… |
GET /webhook/{webhookId} | Get the webhook with the provided id, the caller must be the creator of the webhook. |
POST /webhook/list | Get the list of webhooks for the caller. |
PUT /webhook/{webhookId} | Update the webhook with the given id, the caller must be the creator of the webhook. If the endpoint is modified the webhook verification status will … |
POST /webhook/{webhookId}/verify | Verifies a webhook with the verificationCode received by the endpoint in a WebhookVerificationMessage request. The caller must be the creator of the w… |
PUT /webhook/{webhookId}/verificationCode | When the verification fails or if a verification code is lost or wasn't received, this API allows to sent a new verification code to the webhook endpo… |
DELETE /webhook/{webhookId} | Deletes the webhook with the given id, the caller must be the creator of the webhook. |
WikiPage Services
The Synapse WikiPage model object contains the data needed to render an end-user crafted web page. The Synapse Web Client will dynamically render a WikiPage into a combination of HTML, CSS and Javascript which is then finally rendered as a web page in the client's web browser.
These services provide support for creating, reading, updating, and deleting (CRUD) the WikiPage model objects.
WikiPages are composed of two major parts; the raw markdown text and a list of file attachments. For example, to embed an image from an end-user's machine into a WikiPage, the image file must first be uploaded to Synapse as FileHandle (see File Services). The FileHandle ID can then be added to a WikiPage.attachmentFileHandleIds list. See www.synapse.org for details on the supported markdown syntax.
WikiPages are not stand-alone objects, instead they are a component of another object such as an Entity or Evaluation. For example, when a WikiPage is created for an Entity, the Entity becomes the "owner" of the WikiPage. Access to the WikiPage is always tied to its owner. For example, to GET a WikiPage of an Entity, the caller must have read permission on the Entity.
To navigate the hierarchy of WikiPages associated with an owner use the GET /entity/{ownerId}/wikiheadertree method. The returned list of WikiHeaders can be used to construct a full wiki hierarchy tree for that owner.
Note: WikiPages can be nested to created a hierarchy of sub-pages. However, there can only be one root WikiPage per owner object, and all sub-pages are considered to be owned by the same object as the root page.
Web Services
Resource | Description |
---|---|
POST /entity/{ownerId}/wiki | Create a WikiPage with an Entity as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiPage … |
POST /access_requirement/{ownerId}/wiki | Create a WikiPage with an Access Requirement as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the pass… |
POST /evaluation/{ownerId}/wiki | Create a WikiPage with an Evaluation as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiP… |
GET /entity/{ownerId}/wiki | Get the root WikiPage for an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /evaluation/{ownerId}/wiki | Get the root WikiPage for an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /entity/{ownerId}/wikikey | Get the root WikiPageKey for an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /evaluation/{ownerId}/wikikey | Get the root WikiPageKey for an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /access_requirement/{ownerId}/wikikey | Get the root WikiPageKey for an Access Requirement. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /entity/{ownerId}/wiki/{wikiId} | Get a specific WikiPage of of an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /access_requirement/{ownerId}/wiki/{wikiId} | Get a specific WikiPage of of an Access Requirement. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /evaluation/{ownerId}/wiki/{wikiId} | Get a specific WikiPage of of an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
PUT /access_requirement/{ownerId}/wiki/{wikiId} | Update a specific WikiPage of an Entity. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time a Wiki… |
PUT /entity/{ownerId}/wiki/{wikiId} | Update a specific WikiPage of an Entity. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time a Wiki… |
PUT /evaluation/{ownerId}/wiki/{wikiId} | Update a specific WikiPage of an Evaluation. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time a … |
DELETE /entity/{ownerId}/wiki/{wikiId} | Delete a specific WikiPage of an Entity. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the dele… |
DELETE /evaluation/{ownerId}/wiki/{wikiId} | Delete a specific WikiPage of an Evaluation. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the … |
GET /entity/{ownerId}/wikiheadertree | Get a paginated list of all WikiHeaders that belong to the given owner Entity. The resulting list can be used to build a tree of the WikiPages for thi… |
GET /evaluation/{ownerId}/wikiheadertree | Get a paginated list of all WikiHeaders that belong to the given owner Evaluation. The resulting list can be used to build a tree of the WikiPages for… |
GET /entity/{ownerId}/wiki/{wikiId}/attachmenthandles | Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Entity. This list will include Previews if they exist a… |
GET /evaluation/{ownerId}/wiki/{wikiId}/attachmenthandles | Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Evaluation. This list will include Previews if they exi… |
GET /entity/{ownerId}/wiki/{wikiId}/attachment | Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to… |
GET /evaluation/{ownerId}/wiki/{wikiId}/attachment | Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to… |
GET /entity/{ownerId}/wiki/{wikiId}/attachmentpreview | Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (… |
GET /evaluation/{ownerId}/wiki/{wikiId}/attachmentpreview | Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (… |
WikiPage Services 2
The Synapse V2WikiPage model object contains the data needed to render an end-user crafted web page. The Synapse Web Client will dynamically render a WikiPage into a combination of HTML, CSS and Javascript which is then finally rendered as a web page in the client's web browser.
These services provide support for creating, reading, updating, and deleting (CRUD) the WikiPage model objects.
WikiPages are composed of two major parts; a file that contains the markdown text and a list of file attachments. For example, to embed an image from an end-user's machine into a WikiPage, the image file must first be uploaded to Synapse as FileHandle (see File Services). The FileHandle ID can then be added to a WikiPage.attachmentFileHandleIds list. See www.synapse.org for details on the supported markdown syntax. The markdown text is similarly uploaded as a FileHandle and its FileHandle ID is tracked by the WikiPage.
WikiPages are not stand-alone objects, instead they are a component of another object such as an Entity or Evaluation. For example, when a WikiPage is created for an Entity, the Entity becomes the "owner" of the WikiPage. Access to the WikiPage is always tied to its owner. For example, to GET a WikiPage of an Entity, the caller must have read permission on the Entity.
To navigate the hierarchy of WikiPages associated with an owner use the GET /entity/{ownerId}/wikiheadertree2 method. The returned list of V2WikiHeaders can be used to construct a full wiki hierarchy tree for that owner.
To view a timeline of changes made to a WikiPage, use the GET/entity/{ownerId} /wiki2/{wikiId}/wikihistory method. The returned list of V2WikiHistorySnapshots contain information about who modified the WikiPage and when the changes were made.
Note: WikiPages can be nested to created a hierarchy of sub-pages. However, there can only be one root WikiPage per owner object, and all sub-pages are considered to be owned by the same object as the root page.
Web Services
Resource | Description |
---|---|
POST /entity/{ownerId}/wiki2 | Create a WikiPage with an Entity as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiPage … |
POST /access_requirement/{ownerId}/wiki2 | Create a WikiPage with an AccessRequirement as an owner. Note: The caller must be a member of the Synapse Access and Compliance Team. If the passed Wi… |
POST /evaluation/{ownerId}/wiki2 | Create a WikiPage with an Evaluation as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiP… |
GET /entity/{ownerId}/wiki2 | Get the root WikiPage for an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /access_requirement/{ownerId}/wiki2 | Get the root WikiPage for an AccessRequirement. |
GET /evaluation/{ownerId}/wiki2 | Get the root WikiPage for an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /entity/{ownerId}/wiki2/{wikiId} | Get a specific WikiPage of an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
GET /access_requirement/{ownerId}/wiki2/{wikiId} | Get a specific WikiPage of an Access Requirement. |
GET /evaluation/{ownerId}/wiki2/{wikiId} | Get a specific WikiPage of an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner. |
PUT /entity/{ownerId}/wiki2/{wikiId} | Update a specific WikiPage of an Entity. This adds a new entry to the history of changes made to this specific WikiPage. Synapse employs an Optimistic… |
PUT /entity/{ownerId}/wiki2orderhint | Update an order hint that corresponds to the given owner Entity. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent u… |
PUT /access_requirement/{ownerId}/wiki2/{wikiId} | Update a specific WikiPage of an Access Requirement. This adds a new entry to the history of changes made to this specific WikiPage. Synapse employs a… |
PUT /evaluation/{ownerId}/wiki2/{wikiId} | Update a specific WikiPage of an Evaluation. This adds a new entry to the history of changes made to this specific WikiPage. Synapse employs an Optimi… |
PUT /entity/{ownerId}/wiki2/{wikiId}/{wikiVersion} | For a specific WikiPage of an Entity, restore a version of the WikiPage's content. Synapse employs an Optimistic Concurrency Control (OCC) scheme to h… |
PUT /access_requirement/{ownerId}/wiki2/{wikiId}/{wikiVersion} | For a specific WikiPage of an Access Requirement, restore a version of the WikiPage's content. Synapse employs an Optimistic Concurrency Control (OCC)… |
PUT /evaluation/{ownerId}/wiki2/{wikiId}/{wikiVersion} | For a specific WikiPage of an Evaluation, restore a version of the WikiPage's content. Synapse employs an Optimistic Concurrency Control (OCC) scheme … |
DELETE /entity/{ownerId}/wiki2/{wikiId} | Delete a specific WikiPage of an Entity. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the dele… |
DELETE /access_requirement/{ownerId}/wiki2/{wikiId} | Delete a specific WikiPage of an Access Requirement. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively)… |
DELETE /evaluation/{ownerId}/wiki2/{wikiId} | Delete a specific WikiPage of an Evaluation. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the … |
GET /entity/{ownerId}/wikiheadertree2 | Get a paginated list of all V2WikiHeaders that belong to the given owner Entity. The resulting list can be used to build a tree of the WikiPages for t… |
GET /entity/{ownerId}/wiki2orderhint | Get an order hint that corresponds to the given owner Entity. The resulting hint can be used to establish a relative ordering for the subwikis in a tr… |
GET /access_requirement/{ownerId}/wikiheadertree2 | Get a paginated list of all V2WikiHeaders that belong to the given owner Access Requirement. The resulting list can be used to build a tree of the Wik… |
GET /evaluation/{ownerId}/wikiheadertree2 | Get a paginated list of all V2WikiHeaders that belong to the given owner Evaluation. The resulting list can be used to build a tree of the WikiPages f… |
GET /entity/{ownerId}/wiki2/{wikiId}/wikihistory | Get a paginated list of all V2WikiHistorySnapshot that belong to a specific WikiPage, which belong to the given owner Entity. The resulting list can b… |
GET /access_requirement/{ownerId}/wiki2/{wikiId}/wikihistory | Get a paginated list of all V2WikiHistorySnapshot that belong to a specific WikiPage, which belong to the given owner Access Requirement. The resultin… |
GET /evaluation/{ownerId}/wiki2/{wikiId}/wikihistory | Get a paginated list of all V2WikiHistorySnapshot that belong to a specific WikiPage, which belong to the given owner Evaluation. The resulting list c… |
GET /entity/{ownerId}/wiki2/{wikiId}/attachmenthandles | Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Entity. This list will include Previews if they exist a… |
GET /access_requirement/{ownerId}/wiki2/{wikiId}/attachmenthandles | Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Access Requirement. This list will include Previews if … |
GET /evaluation/{ownerId}/wiki2/{wikiId}/attachmenthandles | Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Evaluation. This list will include Previews if they exi… |
GET /entity/{ownerId}/wiki2/{wikiId}/attachment | Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to… |
GET /access_requirement/{ownerId}/wiki2/{wikiId}/attachment | Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to… |
GET /evaluation/{ownerId}/wiki2/{wikiId}/attachment | Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to… |
GET /entity/{ownerId}/wiki2/{wikiId}/attachmentpreview | Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (… |
GET /access_requirement/{ownerId}/wiki2/{wikiId}/attachmentpreview | Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (… |
GET /evaluation/{ownerId}/wiki2/{wikiId}/attachmentpreview | Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (… |
GET /entity/{ownerId}/wiki2/{wikiId}/markdown | Get a URL that can be used to download the markdown file for a given WikiPage. Note: This call will result in a HTTP temporary redirect (307), to the … |
GET /access_requirement/{ownerId}/wiki2/{wikiId}/markdown | Get a URL that can be used to download the markdown file for a given WikiPage. Note: This call will result in a HTTP temporary redirect (307), to the … |
GET /evaluation/{ownerId}/wiki2/{wikiId}/markdown | Get a URL that can be used to download the markdown file for a given WikiPage. Note: This call will result in a HTTP temporary redirect (307), to the … |