URIs

Revision as of 19:50, 9 November 2022 by Kheitmann (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This is documentation for ART-DECOR Release 2 and tends to be out-dated. Please visit our new documentation site at docs.art-decor.org

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, Template2Example, RetrieveQuestionnaire 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 contents, for instance language=en-US. When no language is entered, the content default language is used. Use language=* for "all languages"
ui User Interface language. When no language is entered, the server default language is used. By default English should be available.
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
https://art-decor.org/decor/services/Template2Example?id=2.16.840.1.113883.3.1937.99.62.3.10.11&effectiveDate=2012-03-11T00:00:00&prefix=demo1- will build an example based on the template id and effectiveDate supplied stoppage at references to other templates (@contains and include)
https://art-decor.org/decor/services/Template2Example?id=2.16.840.1.113883.3.1937.99.62.3.10.11&effectiveDate=2012-03-11T00:00:00&prefix=demo1-&doRecursive=true will build an example based on the template id and effectiveDate supplied traversing all references to other templates (until recursion is found or no more references are left to follow)
https://art-decor.org/decor/services/RetrieveQuestionnaire?id=2.16.840.1.113883.3.1937.99.62.3.4.2&effectiveDate=2012-09-05T16:59:35&language=en-US&ui=nl-NL&format=html will render this transaction through LHCForms

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 and format is html does all repositories. If empty and format is xml does all project metadata optional
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
language Content language - format ll-CC. Recommended with param version. Any '*' without quotes for 'any language' optional
Conformance.svg
ui User Interface language - format ll-CC when format is 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 Content language - format ll-CC. Recommended with param version. Any '*' without quotes for 'any language' optional
Conformance.svg
ui User Interface language - format ll-CC when format is HTML 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 Content language - format ll-CC. Recommended with param version. Any '*' without quotes for 'any language' optional
Conformance.svg
ui User Interface language - format ll-CC when format is 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
interactive Options 'true' (default) or 'false'. Triggers the generation of javascript (onClick) that allows interactive graphics and that should be set to false if the crated sag is about to be uploaded into a CMS where interactive graphics are not allowed. 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
Template2Example prefix Project prefix optional
Conformance.svg
id Template id - format is OID. Only with param prefix, and when no template is POSTed to the service conditional
Conformance.svg
effectiveDate Template effectiveDate - yyyy-mm-ttThh:mm:ss. Only with param id. optional
Conformance.svg
elementId Template element @id - Will trigger the example to be generated from that element onwards optional
Conformance.svg
serialized boolean. Default true when template is POSTed. Default false otherwise. Returns content of <example/> as serialized XML if true, or as XML otherwise optional
Conformance.svg
selectedOnly boolean. Default true when template is POSTed. Default false otherwise. Process only particles marked @selected="" on the incoming template. Imported when POSTed from the visual template-editor where some particles may have been unselected optional
Conformance.svg
recursive boolean. Default false. Process only particles in current template is false and do not proces @contains/include, or recursively follow all references to other templates until that runs into a loop or no more references are left to follow 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), 'cachemeta' (undocumented, internal use only), 'ada-definition' (creates an ADA Definition file suitable as starting point for creating ADA Releases.) optional
Conformance.svg
force Options: 'true', 'false' (default). Relevant only when mode is 'compiled' and on the live version. If true and working on the live version i.e. not on a release, forces recompile if one should already exist. If false or working on a release, compiles when needed or returns the compiled release optional
Conformance.svg
ignoreFilter Options: 'true' (default), 'false'. Relevant only when mode is 'compiled' and on the live version. Use current compile filter settings if any (false) or ignore any filter settings and do a full compile (true). 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
RetrieveQuestionnaire format Return format. Options: 'json', 'html', 'xml' (default). optional
Conformance.svg
id Content transaction id to convert required
Conformance.svg
effectiveDate Content transaction effectiveDate to convert.yyyy-mm-ttThh:mm:ss. Only with param id required
Conformance.svg
version Project release version - format yyyy-mm-ttThh:mm:ss. Only with param prefix optional
Conformance.svg
language Content language - format ll-CC. Recommended with param version. Any '*' without quotes for 'any language' optional
Conformance.svg
fhirLinkItemStyle If set to "id" linkItem value is the id, e.g. "2.16.840.1.113883.3.1937.99.62.3.2.2--2011-01-28T00:00:00", if set to "oid" the OID is shown only, e.g. "2.16.840.1.113883.3.1937.99.62.3.2.2", otherwise the id display name is shown if available, if not and the default is "id. 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
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
Context 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