Difference between revisions of "URIs"

(Implementation status of the query parameters)
(Implementation status of the query parameters)
Line 421: Line 421:
 
! <span id="RetrieveTemplateDiagram">RetrieveTemplateDiagram</span>
 
! <span id="RetrieveTemplateDiagram">RetrieveTemplateDiagram</span>
 
| format
 
| format
| Return format. Options: 'svg' (default), 'xml' (mostly useful for debug)
+
| Return format. Options: 'svg' (default), 'xml' (mostly useful for debug), 'hgraph' (hierarchical graph)
 
| optional [[Image:Conformance.svg|right|20px]]
 
| optional [[Image:Conformance.svg|right|20px]]
 
|-
 
|-

Revision as of 12:01, 16 July 2017

Identification of DECOR objects with URI's.

URI logic

Item Description
server http://art-decor.org/decor/services
separator /
action ProjectIndex, RetrieveDataSet, RetrieveTransaction, RetrieveConcept, RetrieveValueSet, RetrieveOID, RetrieveTemplate , DataSetIndex, TransactionIndex, ValuesetIndex, OIDIndex, TerminologyReport, GetImage, RetrieveIssue, IssueIndex, ProjectLogo, ValidateCode, RetrieveProject
The service RetrieveProject is not a public service because it is only relevant for users who access these services via the database directly in order to produce a publication.
query part and query parameters separator ?
Query parameter Description
id The id of the concept, value set, template or dataset. For instance an OID like: 123 or 123.123.123
code The code of the concept.
codeSystem The codesystem of the concept. For instance an OID like: 123 or 123.123.123
assigningAuthority The responsibleAuthority/code/@code of the OID's returned must match.
effectiveDate The date of the object that id points to as YYYY-MM-DDTHH:mm:ss (2011-12-31T00:00:00). If no date is entered, all versions will be returned. If you use the key word 'dynamic' the latest/current version is returned.
language Language qualifier, for instance language=en-US. When no language is entered, the server's default language is returned and if this is not available, English is returned. By default English should be available. Please note that by passing the language parameter, the HTML-display may return texts in that language.
format The desired return format, for instance format=xml (or: html, csv, pdf). When no format parameter is entered, the default return format is HTML. The HTML and PDF formats have no further specification and are not meant to be automatically parsed.
name The name of value set or template. The value set name (valueSet/@name) or OID-name (id/@name) or template name (template/@name) must be an exact match.
prefix The project prefix (/decor/project/@prefix) must be an exact match.
mode The return type. For instance 'mode=verbatim' returns the project as-is. 'mode=compiled' will resolve external references so the result is self-contained. Please note that 'compiled' is meant to be used for HTML- and Schematrongeneration. The returntype 'compiled' is unsuitable for other uses.
download If download=true, will trigger a download instead of showing output in the browser.
hidecolumns Which columns should be hidden in the returned view. For instance 'hidecolumns=53' will hide columns 3 and 5. After 9, continue in hexadecimal (a, b, c, etc.). Is only applicable for HTML views. See Hidecolumns mapping.

Examples

URI

Description

http://art-decor.org/decor/services/RetrieveValueSet?id=1.2.40.0.34.10.65&effectiveDate=2015-09-01T00:00:00&prefix=elga-&format=xml&language=de-DE

Will return a value set with a specific date in the return format XML

http://art-decor.org/decor/services/RetrieveValueSet?id=1.2.40.0.34.10.65&effectiveDate=2013-01-10T00:00:00&prefix=elga-&format=csv

Will return a value set with a specific date in the return format CSV

http://art-decor.org/decor/services/RetrieveValueSet?id=1.2.40.0.34.10.65&prefix=elga-&format=csv

Will return the latest/current version of a value set in the return format CSV

http://art-decor.org/decor/services/RetrieveValueSet?id=1.2.40.0.34.10.65&prefix=elga-

Will return all versions of a value set in the default return format (HTML)

 http://art-decor.org/decor/services/RetrieveValueSet?id=1.2.40.0.34.10.65&effectiveDate=2015-09-01T00:00:00&prefix=elga-&format=json&language=de-DE

Will return a value set with a specific date in the in the return format JSON

 http://art-decor.org/decor/services/RetrieveValueSet?id=1.2.40.0.34.10.65&effectiveDate=2015-09-01T00:00:00&prefix=elga-&format=sql&language=de-DE

Will return a value set with a specific date in the in the return format SQL

http://art-decor.org/decor/services/RetrieveValueSet?id=1.2.40.0.34.10.65&language=en-US

{for future use} will return all versions of a valueset in the default return format (HTML) in American English

http://art-decor.org/decor/services/RetrieveCode?code=M&codeSystem=2.16.840.1.113883.5.1

{for future use} will return the concept 'Male' of HL7 AdministrativeGender

http://art-decor.org/decor/services/ValueSetIndex

will return a HTML table with formats and versions for all valuesets in DECOR projects, with links to the valuesets.

http://art-decor.org/decor/services/DataSetIndex

will return a HTML table with formats and versions for all datasets in DECOR projects, with links to the datasets.

http://art-decor.org/decor/services/GetImage?prefix=demo-

will return two SVG diagrams for each transactiongroup in the demo DECOR project. One diagram shows the functional perspective and the other shows the technical perspective.

http://art-decor.org/decor/services/GetImage?prefix=demo-&id=2.16.840.1.113883.2.4.3.46.99.3.4.1

will return two SVG diagrams for a specific transactiongroup with id '2.16.840.1.113883.2.4.3.46.99.3.4.1' in the demo DECOR project. One diagram shows the functional perspective and the other shows the technical perspective.

http://art-decor.org/decor/services/OIDIndex

will return a HTML table with an overview for all OIDs from the OID-registry, with links to a detailed view for each OID.

http://art-decor.org/decor/services/OIDIndex?id=1.0.3166.1.2.2

will return a HTML table with an overview for the OID with id '1.0.3166.1.2.2' from the OID-registry, with a link to a detailed view for this OID.

http://art-decor.org/decor/services/OIDIndex?id=1.0.3166.1.2.2&language=de-DE

will return a HTML table with an overview for the OID with id '1.0.3166.1.2.2' from the OID-registry, with a link to a detailed view for this OID in German.

http://art-decor.org/decor/services/RetrieveOID?id=1.0.3166.1.2.2&format=html

will return a HTML table with a detailed view for the OID with id '1.0.3166.1.2.2' from the OID-registry, with links to a XML view for this OID.

http://art-decor.org/decor/services/RetrieveOID?id=1.0.3166.1.2.2&format=html&language=de-DE

will return a HTML table with a detailed view in German for the OID with id '1.0.3166.1.2.2' from the OID-registry, with links to a XML view for this OID.

http://art-decor.org/decor/services/TransactionIndex?format=html&language=en-US

will return a HTML table with all transactions in American English

http://art-decor.org/decor/services/TransactionIndex?prefix=demo3-&format=html&language=en-US

will return a HTML table with all transactions from the DECOR project demo3- in American English

http://art-decor.org/decor/services/RetrieveTransaction?id=2.16.840.1.113883.3.1937.99.60.3.4.2&format=html&language=en-US

will return a HTML table for the transaction with id 2.16.840.1.113883.3.1937.99.60.3.4.2 (Electrocardiogram Report) in American English

http://art-decor.org/decor/services/RetrieveTemplate?id=2.16.840.1.113883.3.1937.99.60.3.10.3001&prefix=demo3-&format=xml

will return a original template in raw format with id 2.16.840.1.113883.3.1937.99.60.3.10.3001 (Electrocardiogram Report) in project demo3

http://art-decor.org/decor/services/Template2XSL?id=2.16.840.1.113883.3.1937.99.60.3.10.3001&prefix=demo3-&format=html

will return a HTML overview of generated XSLTs based on template id 2.16.840.1.113883.3.1937.99.60.3.10.3001 in project demo3

http://art-decor.org/decor/services/Template2XSL?id=2.16.840.1.113883.3.1937.99.60.3.10.3001&prefix=demo3-&format=xsl

will return the generated XSLT for template 2.16.840.1.113883.3.1937.99.60.3.10.3001 in project demo3

http://art-decor.org/decor/services/RetrieveConcept?conceptId=2.16.840.1.113883.3.1937.99.62.3.2.3&conceptEffectiveDate=2011-01-28T00:00:00&language=en-US will return info for the concept Weight inside the dataset of the demo1- project

Implementation status of the query parameters

Each query parameter marked with Conformance.svg is implemented at this moment. Each query parameter marked with N/A is not applicable, not implemented at this moment.

Service Name Parameter Description Status
ProjectIndex format Return format. Options: 'html' (default), 'xml' optional
Conformance.svg
prefix Project prefix - if empty does all repositories optional
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
language Project release language - format ll-CC. Recommended with param version. Also UI language with format HTML optional
Conformance.svg
view Options: 'd' Limits index to datasets, 't' limits view to transactions, 'v' limits index to value sets, 'r' limits index to templates (rules). optional
Conformance.svg
DataSetIndex Shortcut to Projectindex?view=d
TransactionIndex Shortcut to Projectindex?view=t
ValueSetIndex Shortcut to Projectindex?view=v
TemplateIndex Shortcut to Projectindex?view=r
OIDIndex prefix Registry prefix - if empty does all registries. Note: was parameter registry (still exists but deprecated) optional
Conformance.svg
language UI language with format HTML - format ll-CC. optional
Conformance.svg
id OID to filter list on optional
Conformance.svg
name OID name to filter list on optional
Conformance.svg
assigningAuthority OID assigning authority to filter list on optional
Conformance.svg
effectiveDate OID effective date to filter list on optional
Conformance.svg
RetrieveConcept Shortcut to RetrieveTransaction where param id is optional may be either a dataset or a transaction, and param conceptId shall have a value. If param id does not have a value, then the dataset that holds the concept is assumed. See RetrieveTransaction for other parameters
RetrieveDataset Shortcut to RetrieveTransaction where param id shall be a dataset. See RetrieveTransaction for other parameters
RetrieveTransaction format Return format. Options: 'html' (default), 'xml', 'hlist' (hierarchical list) optional
Conformance.svg
prefix Project prefix. A dataset/transaction/concept is assumed to be in exactly one project, so param prefix is not necessary optional
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
language Project release language - format ll-CC. Recommended with param version. Also UI language with format HTML optional
Conformance.svg
id Dataset/Transaction id - format is OID. Param id and/or conceptId is required. optional
Conformance.svg
effectiveDate Dataset/Transaction effectiveDate - yyyy-mm-ttThh:mm:ss. Only with param id. optional
Conformance.svg
conceptId Concept id - format is OID. Param id and/or conceptId is required. optional
Conformance.svg
conceptEffectiveDate Concept effectiveDate - yyyy-mm-ttThh:mm:ss. Only with param conceptId. optional
Conformance.svg
community Community prefix. This parameter may repeat. Can only include communities with guest access enabled optional
Conformance.svg
unfiltered Options 'true' or 'false' (default). If true, shows any deprecated/cancelled/rejected concepts that may be in the dataset. If absent or 'false', those are hidden. Is always 'true' i.e. irrelevant for transactions. optional
Conformance.svg
collapsed Options 'true' (default) or 'false'. If true, groups start collapsed. optional
Conformance.svg
draggable Options 'true' (default) or 'false'. If false, dragging of columns is disabled. Since draggable columns can't be selected with the mouse, useful if one wants to copy data. optional
Conformance.svg
download Options 'true' (default) or 'false'. Triggers a download. optional
Conformance.svg
hidecolumns Alphanumeric indicator of columns that should be hidden upon launch. Default set is . Options: see below optional
Conformance.svg
RetrieveConceptDiagram format Return format. Options: 'svg' (default) optional
Conformance.svg
language Project release language - format ll-CC. Recommended with param version. Also UI language with format HTML optional
Conformance.svg
datasetId Format is OID. Need param transactionId or datasetId conditional
Conformance.svg
datasetEffectiveDate Format is yyyy-mm-ddThh:mm:ss. Only relevant with param datasetId optional
Conformance.svg
transactionId Format is OID. Need param transactionId or datasetId conditional
Conformance.svg
transactionEffectiveDate Format is yyyy-mm-ddThh:mm:ss. Only relevant with param transactionId optional
Conformance.svg
id Concept id. Format is OID. optional
Conformance.svg
effectiveDate Concept effective date. Format is yyyy-mm-ddThh:mm:ss. Only relevant with param id optional
Conformance.svg
RetrieveValueSet format Return format. Options: 'html' (default), 'xml' (ART-DECOR), 'csv', 'svs' (IHE SVS 2) optional
Conformance.svg
inline Relevant only with format=html. Options 'true' and 'false' (default). Omits HTML header info. Useful for inclusion of HTML in other pages. optional
Conformance.svg
prefix Project prefix. Doesn't return anything without prefix. required
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
language Project release language - format ll-CC. Recommended with param version. Also UI language with format HTML optional
Conformance.svg
id Value set id - format is OID. Only with param prefix. When omitted checks param name optional
Conformance.svg
name Value set name - format is string. Only with param prefix. Only checked when id is omitted. When both id and name are omitted checks param ref optional
Conformance.svg
ref Value set id or name - format is OID or string. Only with param prefix. Only checked when both id and name are omitted. When id, name and ref are omitted all project value sets are returned. optional
Conformance.svg
effectiveDate Value set effectiveDate - yyyy-mm-ttThh:mm:ss. Only with param id, name, or ref. optional
Conformance.svg
RetrieveTemplate format Return format. Options: 'html' (default), 'xml' (pure raw template (versions) wrapped in <rules/> element , 'expandedxml' (expanded template (versions) wrapped in <rules/> element, expands includes, associations etc.), 'xmlnowrapper' (pure first matching raw template) optional
Conformance.svg
inline Relevant only with format=html. Options 'true' and 'false' (default). Omits HTML header info. Useful for inclusion of HTML in other pages. optional
Conformance.svg
prefix Project prefix required
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
language Project release language - format ll-CC. Recommended with param version. Also UI language with format HTML optional
Conformance.svg
id Template id - format is OID. Only with param prefix required
Conformance.svg
effectiveDate Template effectiveDate - yyyy-mm-ttThh:mm:ss. Only with param id. optional
Conformance.svg
RetrieveTemplateDiagram format Return format. Options: 'svg' (default), 'xml' (mostly useful for debug), 'hgraph' (hierarchical graph) optional
Conformance.svg
prefix Project prefix required
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix not implemented
language Project release language - format ll-CC. Recommended with param version. Also UI language with format HTML optional
Conformance.svg
id Template id - format is OID. Only with param prefix required
Conformance.svg
effectiveDate Template effectiveDate - yyyy-mm-ttThh:mm:ss. Only with param id. optional
Conformance.svg
RetrieveOID format Return format. Options: 'html' (default), 'xml' optional
Conformance.svg
prefix Registry prefix - if empty does all registries. Note: was parameter registry (still exists but deprecated) required
Conformance.svg
language UI language with param format=html - format ll-CC. optional
Conformance.svg
id OID optional
Conformance.svg
name OID name/description optional
Conformance.svg
statusCode OID status code optional
Conformance.svg
RetrieveIssue Currently returns XML only and does not have an interface
id OID of the issue required
Conformance.svg
IssueIndex Currently returns XML only and does not have an interface
prefix Project prefix. Note: prefix was added in 1.6.11 to align with the other services. Parameter project remains supported. required
Conformance.svg
searchString List of terms that results should match in issue/@displayName or any desc element. Results all if empty optional
Conformance.svg
type List of issue/@type values that results should have. Returns all if empty optional
Conformance.svg
priority List of issue/@priority values that results should have. Returns all if empty optional
Conformance.svg
statusCode List of issue most recent status code values that results should have. Returns all if empty optional
Conformance.svg
assignedTo List of project/author/@id values that the latest assigned person of the issue should match. Returns all if empty optional
Conformance.svg
labels List of issue most recent label code values that results should have. Returns all if empty optional
Conformance.svg
sort Singular value to sort on. Supported are 'issue' (display name),'priority','type','status','date','assigned-to','label'. There's no default. optional
Conformance.svg
max Maximum number of results with minimum 1. Default is 75 optional
Conformance.svg

(since DECOR services 1.6.6)
prefix Project prefix. required
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
logo Project logo. If not provided will return the project/reference/@logo or if even that is empty will return the server default logo. You may specify any logo name such as a copyright logo. Any logo is expected to come from the collection prefix-logos which is also the place where you upload logos through the ART project form. optional
Conformance.svg
mode Options: (default - retrieves the requested logo), 'list' (lists available logos) optional
Conformance.svg
RetrieveProject format Return format. Options: 'html' (default when param prefix is omitted), 'xml' (default in all other cases) optional
Conformance.svg
prefix Project prefix - if empty shows HTML form that guides you. required
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
language Project release language - format ll-CC. Recommended with param version. Also UI language with format HTML optional
Conformance.svg
mode Options: 'verbatim' (default - raw project file), 'compiled' (resolves references and inherits, adds id info, suitable for publication purposes), 'test' (undocumented) optional
Conformance.svg
download Options: 'true', 'false' (default) optional
Conformance.svg
ValidateCode
(since DECOR services 1.8.27)
prefix Project prefix. required
Conformance.svg
id ValueSet id - format is OID. required
Conformance.svg
effectiveDate ValueSet effectiveDate - yyyy-mm-ttThh:mm:ss. Only with param id. optional
Conformance.svg
code code to check optional
Conformance.svg
codeSystem codeSystem to check optional
Conformance.svg

Implementation status of the return formats

Each format marked with Conformance.svg is implemented at this moment.

Retrieve

Dataset

Retrieve

Transaction

Retrieve

Valueset

Retrieve

Code

Retrieve

OID

Retrieve

Concept

Retrieve

Project

Retrieve

Template

XML Conformance.svg Conformance.svg Conformance.svg Conformance.svg Conformance.svg Conformance.svg Conformance.svg Conformance.svg
CSV no no Conformance.svg no no no no no
HTML Conformance.svg Conformance.svg Conformance.svg Conformance.svg Conformance.svg Conformance.svg no Conformance.svg
SQL no no Conformance.svg no no no no no
FHIR (DSTU2) no no Conformance.svg no no no no no
FHIR (STU3) no no Conformance.svg no no no no no
PDF for future use possibly possibly no no no no no

All *Index resources are only returned in HTML format.

Hidecolumns mapping

The query parameter hidecolumns can contain numbers and letters (the order is not significant) which represent the columns in the returned view, with the following mapping:

Column to hide hidecolumn contains
Name N/A
ID 2
Mandatory 3
Conformance (transaction) 4
Cardinality (transaction) 5
Max (transaction) 6
Cardinality/conformance/datatype column (convenience single column) (transaction) 0
Datatype 7
Unit 8
Example 9
Codes a
Description b
Source c
Rationale d
Operationalization e
Comment f
Condition (transaction) g
Status column h
Community column i
Terminology column j
Value set column k
Type column (group / item) l
Parent column m
Inherit column n
Mapping o
CCD (Combined conformance, cardinality, datatype) p

Error handling

When a resource does not exist (either the queried format does not exist, or the resource does not exist in that language, etc) a HTTP 404 error is returned.

Local value sets vs external value sets

In DECOR value sets can be defined locally (only applicable to that DECOR project). Value sets that are defined locally in the DECOR project, do have an id (OID) and a (local) name. Local value sets can contain a statusCode.

External value sets always contain an id (OID).

A value set must always contain an effectiveDate, which contains the "creation" date of the value set.

FHIR URI's

For FHIR URI's, see: FHIR URI's