Home / Share / SHARE API User Documentation

SHARE API User Documentation

Welcome to CDISC SHARE, the global, cloud-based metadata repository of curated clinical and translational research standards and semantics. SHARE creates, reuses and manages CDISC standards’ metadata to improve the quality, reusability and integration across CDISC standards and controlled terminologies. With SHARE, standards are no longer trapped in PDFs, where they must be extracted to use in your databases, software and systems. SHARE contains metadata content from models and implementation guides from classes, domains, variables, etc. that tell what each is, and how to comply with the standard when implementing it in your organization.

SHARE also features an Application Programming Interface (API) to enable other systems’ access to SHARE content, facilitating the implementation of CDISC standards, and further automating clinical research processes.

Why Use SHARE and Its API?

SHARE is beneficial to all organizations engaged in regulated, pre-clinical and clinical research as it enables technological innovation and:

  1. Saves time. CDISC standards are available in real time through the SHARE API.
  2. Helps ensure compliance. SHARE provides access to multiple file types of CDISC standards required for new submissions to FDA and PMDA.
  3. Facilitates impact assessments. SHARE allows the creation of “Diff files,” which specify what has changed from one version of a standard to the next, facilitating analysis of how your reports and data management systems will be affected when your organization adopts the latest version of a CDISC standard.
  4. Interconnects standards. Using SHARE, you can easily interrogate across CDISC standards to determine where the same variable is used in two or more standards. These points of interconnected metadata also link data collected during the course of a protocol, improving data quality with consistent metadata reuse.
  5. Supports end-to-end standards. CDISC standards cover the complete clinical research lifecycle from electronic health record and protocol design through statistical planning, case report form design, data collection and tabulation, analysis and reporting. Implementing these interconnected standards in your systems from the earliest phase of a trial to its conclusion allows you to trace the same data element throughout the trial lifecycle.

These benefits exist for you regardless of whether your organization has a metadata repository or not.

If your organization has a metadata repository, exports from SHARE can be imported through the SHARE API into your system as a CDISC library. End users can use the SHARE API-aware MDR products to automatically update their repositories with the latest CDISC standards content. These standards can then be deployed and synchronized across multiple systems in your organization at once.

If your organization does not have an MDR, SHARE exports and the SHARE API can still support research IT and compliance. If you use CDISC standards in multiple programs (either those you have written that run on your localhost or on a remote server), databases and applications, you can use the API to perform updates for each of these systems (below, right).

The Scope of This Tutorial

Employees of CDISC Member organizations can download CDISC standards in multiple file types (e.g., SHARE-XML, RDF*, experimental JSON) from the SHARE API. In this tutorial, you will learn how to request an API account, identify endpoints exposed by the service, and determine the impact of standards content that has changed from one release to the next. Because each organization’s data management, analysis and reporting systems are unique, specific guidance on how to precisely implement SHARE’s standards in your organization should be determined at each organization accordingly.

This tutorial is for the SHARE API only; if you prefer to download individual CDISC standards as Excel, CSV or other formats, please see our SHARE for Data Managers tutorial.

Required Skills & Software Programs:

  • Knowledge of CDISC standards and how they are implemented in your organization
  • Experience with programming languages such as Java, Python, SAS, C dialects or Perl and with using web services
  • Your favorite IDEs (Integrated Development Environments)

For information on web APIs and REST protocols, please review external sources.

*For RDF downloads, graph databases and SPARQL are required, which are out of scope for this document.


SHARE Computable Standards Metadata

SHARE publishes CDISC standards metadata in a number of computable formats, including:

  • ODM v1.3.2
  • Define-XML v2.0
  • SHARE-XML extended ODM v1.3.2 and Define-XML v2.0
  • OWL/RDF
  • Excel
  • JSON (API access is experimental only for API version 1.0)

 

SHARE-XML contains additional metadata that ODM and Define alone do not.


High-level View of the SHARE ISO 11179-based Metamodel

CDISC Standards’ models/specifications, classes and domains are all managed in SHARE as Metadata Element Sets (MDES). Variables are MDEs.

SHARE formalizes relationships among metadata elements such as domains, variables, and codelists and shows how variables are related across the clinical research data lifecycle to support end-to-end standards implementation and process automation. These relationships in SHARE are displayed below as Mapped from, Maps to Variable, and Maps To BRIDG, in addition to other related content. This interconnection links CDISC standards through the full clinical lifecycle and supports transforming CDASH data into SDTM for tabulation and SDTM data to ADaM for analysis.

Bringing this together, the SHARE visualization below generated from the CDASH Demographics SEX variable uses a layered view to show the first level of elements related to the variable. In this visualization the variables are labeled as metadata elements. The CDASH SEX variable maps-to the SDTM variable in the same metadata element layer. The CDASH SEX variable also maps-to BRIDG variables in the same layer. The SEX variables implement the concept of Sex with NCI EVS (Enterprise Vocabulary Services) code C282421, as shown in the layer above the variables. Below the variables, the Metadata Element Set layer shows that the CDASH DM domain includes the SEX variable. The bottom layer shows the SEX value domain that represents the set of permissible values for the SEX variable, which in this case represents those values in the Sex code list.


SHARE Schema

Title

Standards List

URL

/standards

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/standards?user-id=bus_user&encoding=identity

See detailed examples

 

 

Title

Standard Metadata

URL

/standards/{asset-id}/metadata

Method

Get

Required Params

user-id=[valid user id]

Optional Params

media-type=[xml (default) or rdf-xml or turtle or n-triples]

encoding=[identity or zip or gzip (default)]

rdf-semantic-info=[true or false]

deferred=[true or false]

Response Codes

Response Codes

Example

/standards/1.0_1391054074081152706575/metadata?user-id=bus_user&media-type=xml&encoding=identity

See detailed examples

 

 

Title

Standard Classes

URL

/standards/{asset-id}/classes

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/standards/1.0_1391054074081152706575/classes?user-id=bus_user&media-type=xml&encoding=identity

See detailed examples

 

 

Title

Standard Domains

URL

/standards/{asset-id}/domains

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/standards/1.0_1391054074081152706575/domains?user-id=bus_user&media-type=xml&encoding=identity

 

 

Title

Class Domains

URL

/classes/{asset-id}/domains

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/classes/1.0_1391054070446193837850/domains?user-id=bus_user&lifecycle-status=Approved Final&media-type=xml&encoding=identity

 

 

Title

Class Model Variables

URL

/classes/{asset-id}/model-variables

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/classes/1.0_1391054070446193837850/model-variables?user-id=bus_user&media-type=xml&encoding=identity

 

 

Title

Domain Variables

URL

/domains/{asset-id}/variables

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/domains/1.0_1391054058621-1072466354/variables?user-id=bus_user&media-type=xml&lifecycle-status=Approved Final&encoding=identity

 

 

Title

Standard Terminology Package List

URL

/terminology-packages

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/terminology-packages?user-id=ds_user&lifecycle-status=Approved Final&media-type=xml&encoding=identity

Title

Standard Terminology List

URL

/terminology-packages/{asset-id}/terminologies

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/terminology-packages/1.0_1390986288682 1633505819/terminologies?user-id=bus_user&lifecycle-status=Approved Final&media-type=xml&encoding=identity

 

 

Title

NCI/EVS Terminology Package Content

URL

/standards/{asset-id}/metadata

Method

Get

Required Params

user-id=[valid user id]

Optional Params

media-type=[xml (default) or rdf-xml or turtle or n-triples]

encoding=[identity or zip or gzip (default)]

deferred=[true or false]

Response Codes

Response Codes

Example

/standards/1.0_13909862886802094447920/metadata?user-id=ds_user&media-type=xml&encoding=identity

 

 

Title

Standard Terminology

URL

/standards/{asset-id}/metadata

Method

Get

Required Params

user-id=[valid user id]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/standards/1.0_1390967398101-686138911/metadata?user-id=bus_user&media-type=xml&encoding=identity

 

 

Title

Search Term List

URL

/terminology/terms

Method

Get

Required Params

user-id=[valid user id]

search-term=[string]

Optional Params

lifecycle-status=[ Approved Final (default) or Approved Provisional]

media-type=[xml (default) or json (alpha)]

encoding=[identity or zip or gzip (default)]

Response Codes

Response Codes

Example

/terminology/terms?user-id=ds_user&lifecycle-status=Approved Final&search-term=UNKNOWN&encoding=identity

See detailed examples

Response Codes

Code

Phrase

Description

200

OK

The request was processed successfully.

202

Accepted

The request has been accepted for further processing of a deferred response.

204

No Content

The request was processed successfully, but no matching content was found. Indicates the asset id exists, but the request returned no content.

400

Bad Request

Server cannot process request due to client error like a malformed request. This code is also returned for an invalid optional query parameter to communicate that a problem exists with the request.

401

Unauthorized

Request not processed due to invalid authorization header or authentication failure. When the user id in the query parameter is invalid a response code of 400 is returned.

404

Not Found

Requested an invalid Library Name or Asset ID. In this case, the library or asset id does not exist.

405

Method Not Allowed

Unsupported HTTP method.

406

Not Acceptable

Request not processed due to invalid Media Type specified in the HTTP header.

409

Conflict

Indicates the requested asset is locked. A 409 will be returned if the requesting role does not have the required permissions.

500

Internal Server Error

Server encountered an unexpected condition to serve the request.

 

Request and Response Headers

Request Header

Accept

application/xml

Request a resource in ODM/XML format

application/json

Request a resource in JSON format

application/rdf-xml

Request a resource in RDF/XML format

text/turtle

Request a resource in RDF Turtle format

application/n-triples

Request a resource as RDF N-Triples

Accept-Encoding

zip

Request encoding in ZIP format

Response Header

 

 

 

Content-Type

application/xml

Return a resource in ODM/XML format

application/json

Return a resource in JSON format

application/rdf-xml

Return a resource in RDF/XML format

text/turtle

Return a resource in RDF Turtle format

application/n-triples

Return a resource as RDF N-Triples

Content-Encoding

zip

Return a resource encoded in ZIP format


In 2016, CDISC and six participating organizations carried out a SHARE API Pilot. Business and Decision Life Sciences, EDETEK, Entimo, eTRIKS, and Fujitsu have all developed products that utilize the SHARE API.