1 Related JIRA
2 Introduction
3 Requirements
4 Existing API
5 Proposed API Changes
- 5.1 Portals API:
  - 5.1.1 Models:
    - 5.1.1.1 Portal
    - 5.1.1.2 CreateOrUpdatePortalRequest
    - 5.1.1.3 ListPortalPageResponse
- 5.2 DOI API
  - 5.2.1 DOI Association Model
  - 5.2.2 DataciteMetadata Model
  - 5.2.3 POST /doi/async/start
  - 5.2.4 GET /doi/locate API
  - 5.2.5 GET /doi
  - 5.2.6 GET /doi/association

Related JIRA

PLFM-8536 - Getting issue details... STATUS

PLFM-8734 - Getting issue details... STATUS

DESIGN-807 - Getting issue details... STATUS

Introduction

Today Synapse allows to mint a DOI for any entity in Synapse (project, folder, dataset, file etc.). DOI support in Synapse was introduced early on and went through (at least one) revision and we have a dedicated API that allows users that have UPDATE permission on an entity to mint a DOI.

The ecosystem of Synapse expanded with the introduction of dissemination portals that are focused on specific research areas, examples are the https://adknowledgeportal.synapse.org/ and the https://cancercomplexity.synapse.org/. The portals are built on top of Synapse and expand the context in which an entity might be viewed by a data consumer, for example a study in the AD Knowledge Portal uses a Synapse entity folder to store its raw content and it is rendered in the portal with additional context (e.g. https://adknowledgeportal.synapse.org/Explore/Studies ).

The portals are central to the dissemination of knowledge and while Synapse is listed as a generalist repository by NIH (https://www.nlm.nih.gov/NIHbmic/generalist_repositories.html ), we now have at least two portals (ADKP and Cancer Complexity) that are listed as domain-specific repositories by NIH (https://www.nlm.nih.gov/NIHbmic/domain_specific_repositories.html ).

While the data is actually hosted in Synapse, the main way to present the data to the consumer should go through the selected domain-specific repositories. This implies that it should be possible to have DOIs that point to the dissemination portal resources. For example, to cite a study from ADKP we should be able to mint a DOI for the specific study in the ADKP, rather than the underlying synapse folder that the study uses as part of its representation.

Requirements

It should be possible for a Portal administrator to mint a DOI that points to a portal resource directly from the Portal
We only support portal resources that rely on a Synapse entity. For example, Studies, Grants etc; Example of resources that might not be represented by a synapse entity are Portal Programs, Projects and Publications). ← We decided to remove this constraint since the link between a portal resource and a Synapse entity is just an artifact and not always followed (e.g. some resources do not have a specific entity representation)
Existing DOIs that already point to the Synapse.org landing page do not need to be updated to point to a Portal
A DOI minted from a portal can have its own publisher, currently we hardcode the Synapse publisher that is registered in the https://ror.org/.

Existing API

The existing DOI API uses an async job to mint or update a DOI, the request body has a doi property defined with the following properties:

"properties": {
    "creators": {
        "type": "array",
        "items": {
              "$ref": "#/components/schemas/org.sagebionetworks.repo.model.doi.v2.DoiCreator",
              "description": "JSON schema for DOI Metadata Creator."
        },
        "description": "Required. The main researchers involved in producing the data, or the authors of the publication, in priority order."
    },
    "titles": {
        "type": "array",
        "items": {
              "$ref": "#/components/schemas/org.sagebionetworks.repo.model.doi.v2.DoiTitle",
              "description": "JSON schema for DOI Metadata Title."
        },
        "description": "Required. A name or title by which a resource is known."
    },
    "publicationYear": {
        "type": "integer",
        "format": "int32"
    },
    "resourceType": {
        "$ref": "#/components/schemas/org.sagebionetworks.repo.model.doi.v2.DoiResourceType",
        "description": "Required. Describes the type of media that the DOI Metadata refers to."
    },
    "associationId": {"type": "string"},
    "etag": {"type": "string"},
    "doiUri": {"type": "string"},
    "doiUrl": {"type": "string"},
    "objectId": {"type": "string"},
    "objectType": {"type": "string"},
    "objectVersion": {
        "type": "integer",
        "format": "int32"
    },
    "associatedBy": {"type": "string"},
    "associatedOn": {"type": "string"},
    "updatedBy": {"type": "string"},
    "updatedOn": {"type": "string"}
}

An example of minted DOI is as follows:

URI: 10.5072/syn123.2

URL: https://repo-prod.prod.sagebase.org/repo/v1/doi/locate?id=syn123&version=2&type=ENTITY

Note that the URL for the DOI points to the synapse backend API and on a GET request will issue a redirect to:

https://www.synapse.org/#!Synapse:123/version/2

In simple terms the API takes in input the synapse entity id (and optional version) plus the DOI metadata and creates a handler that points to the backend /locate API with the necessary parameters to resolve the entity page in the Synapse.org portal.

Proposed API Changes

In order to support the portals scenario, we propose to introduce a new set of APIs to manage a portal, a Portal object will have its own ACL.

Portals API:

URL	Request	Response	Description

URL	Request	Response	Description
POST /portals	CreateOrUpdatePortalRequest	Portal	Register a new Portal with Synapse, only synapse administrators can invoke this API. The user will be automatically assigned all the ACL for the portal (update, permissions etc).
PUT /portals/{id}	CreateOrUpdatePortalRequest	Portal	Updates the metadata of the portal with the id in the path. Only users with UPDATE permissions are allowed to perform this operation.
GET /portals?		ListPortalPageResponse	Allows to fetch a page of portals, any user can invoke this operation. We might want to add filters by url, or name.
GET /portals/{id}		Portal	Fetches a portal with the id in the path. Any user can invoke this operation
GET /portals/{id}/acl		AccessControlList	Fetches the ACL for the portal with the id in the path. An ACL will always exist for a portal. Any user can invoke this operation.
PUT /portals/{id}/acl	AccessControlList	AccessControlList	Updates the ACL for the portal with the id in the path. Only users with CHANGE_PERMISSIONS permission can update the ACL.

Models:

Portal

{
	"description": "JSON schema for a Synapse Portal.",
	"properties": {
		"id": {
			"description": "The unique ID issued for this Portal. Generated by Synapse",
			"type": "integer"
		},
		"etag": {
			"type": "string",
			"description": "For Optimistic Concurrency Control (OCC)."
		},
		"name": {
			"description": "The name of the portal, must be unique.",
			"type": "string"
		},
		"url": {
			"description": "The base URL of the portal, must be unique.",
			"type": "string"
		},
		"createdBy": {
			"description": "The ID of the user that created the portal.",
			"type": "string"
		},
		"createdOn": {
			"type": "string",
			"format": "date-time",
			"description": "The date time this Portal was first created"
		},
		"updatedBy": {
			"description": "The ID of the user that updated the portal.",
			"type": "string"
		},
		"updatedOn": {
			"type": "string",
			"format": "date-time",
			"description": "The date time this POrtal was last updated."
		}
	}
}

CreateOrUpdatePortalRequest

{
	"description": "JSON schema for a request to create or update a Portal.",
	"properties": {
		"etag": {
			"type": "string",
			"description": "For Optimistic Concurrency Control (OCC)."
		},
		"name": {
			"description": "The name of the portal, must be unique.",
			"type": "string"
		},
		"url": {
			"description": "The base URL of the portal, must be unique.",
			"type": "string"
		}
	}
}

ListPortalPageResponse

DOI API

In order to support a portal in the DOI API operations we can introduce a new portalId property in all the models and API parameters that are used throughout the API, this allows to specify a portal that the DOI operation refers to. For backward compatibility if a portalId parameter is omitted the backend will treat it as referring to the default Synapse.org portal and will have a special bootstrapped internal value (e.g. 1).

Additionally, we need to introduce a new URI scheme for DOIs that are minted for a portal, currently minting a DOI for an entity references the synapse id:

DOI URI: 10.5072/syn123.2

DOI URL: https://repo-prod.prod.sagebase.org/repo/v1/doi/locate?id=syn123&version=2&type=ENTITY

Given that for each minted DOI we generate a unique identifier (the associationId), going forward we will be using that id instead which is opaque and not bound to a specific entity or portal.

For example, suppose that portal 456 points to https://portal.synapse.org and we want to mint a DOI for STUDY syn123, the client would issue a request with portalId=456 and objectId=STUDY.syn123 (note that the objectId is opaque to synapse for a portal) and the DOI would look like:

DOI URI: 10.5072/1234567

DOI URL: https://repo-prod.prod.sagebase.org/repo/v1/doi/locate?portalId=456&id=STUDY.syn123

The backend would resolve the URL above to:

https://portal.synapse.org/doi?id=STUDY.syn123

DOI Association Model

A DOI Association is used when minting or updating a DOI, in particular it contains the reference to the entity id/version that the DOI is minted for, we add the optional portalId property. The portalId will become part of the unique key of the association. Note that when a portalId is supplied the objectId is treated as an opaque identifier and the objectType will be PORTAL_RESOURCE. Additionally, the objectVersion is ignored.

Additionally, we change the objectType enumeration from https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/ObjectType.html to a dedicated https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/doi/v2/DoiObjectType.html that will have as possible values ENTITY or PORTAL_RESOURCE.

DataciteMetadata Model

We expose the publisher property, historically we minted DOIs using the Synapse publisher (registered in the research organization registry), but for a portal we will use the Portal.name property instead:

POST /doi/async/start

The DOI association model in the request will allow the optional portalId property as explained above. The only other change required for this API is that if a portalId is included and it is different than the internal Synapse portal id, the user invoking the operation needs to have CREATE permission on the portal with the given id. This allows to assign multiple users permissions to mint DOIs from a portal, without the users being able to edit the portal or portal ACL.

GET /doi/locate API

We add the portalId parameters to the locate API that when present will trigger the resolution to the portal URL. If omitted will generate the current URL to the synapse.org portal.

GET /doi

We add the optional portalId parameter to the get API, so that the portal can fetch the DOI information, in this case the only value allowed for the type parameter is PORTAL_RESOURCE. If portalId is omitted will fetch the DOI information for the synapse.org portal.

GET /doi/association

Similarly to the previous APIs, we add the optional portalId parameter to the get association API. If omitted will fetch the DOI association for the synapse.org portal.

Synapse Platform

Dissemination Portals Support

Analytics