API version 3 Reference

Documentation and Lists

GET

• …/ # returns the welcome page with information and links about the mdTranslator
• …/api/readers # returns a list of support mdTranslator readers
• …/api/readers/{reader} # returns documentation for a specific mdTranslator reader
• …/api/writers # returns a list of support mdTranslator readers
• …/api/writers/{writer} # returns documentation for a specific mdTranslator reader

• …/api/codelists # returns a JSON or XML object with all codeLists from mdCodes
  
  • for codelists in ISO CT_CodelistCatalogue format use …/api/codelists.xml
  • for codelists in a JSON object use …/api/codelists.json
    • add definitions=”true” to include code descriptions …/api/codelists?format=json&definitions=true
    • add showDeprecated=”true” to include deprecated codes …/api/codelists?format=json&showDeprecated=true
    • add callback=”{callbackName}” for JSONp …/api/codelists?format=json&callback=myJsonP
• …/api/codelists/{codeListName} # returns a JSON object with a specified codeList
  • add definitions=”true” to include code descriptions …/api/codelists/iso_role?definitions=true
  • add showDeprecated=”true” to include deprecated codes …/api/codelists?format=json&showDeprecated=true
  • add callback=”{callbackName}” for JSONp …/api/codelists/iso_role?callback=myJsonP

• …/api # returns documentation on the mdTranslator API
• …/api/v3 # returns documentation on the mdTranslator API (alternate link)
• …/api/v3/options # returns a JSON object with all supported mdTranslator options;
  • intended for loading mdTranslator option lists into automated tools
  • use option callback=”{callbackName}” for JSONp
• …/api/v3/demo # access to demo page to view and test mdTranslator options

Translator Methods

GET

• …/api/v3/translator?{options} # returns metadata from the mdTranslator according to options specified
  • accepts requests with options encoded as key-value pairs in the query string.
  • only recommended for use when JSONp is required, i.e. for clients without CORS support.
  • Note: subject to URI size limits

POST

• …/api/v3/translator?{options} # returns metadata from the mdTranslator according to options specified
  • accepts application/x-www-form-urlencoded requests with options encoded as key-value pairs.

Options

file (string) required

the input file to be translated by mdTranslator.
the format of the file must be provided in the ‘reader=’ option.

reader= [mdJson | fgdc | sbJson] required

specifies a reader for the mdTranslator

writer= [html | fgdc | iso19115_2 | iso19110 | mdJson | sbJson]

specifies a writer for the mdTranslator;
a null writer will validate input only

validate= [none | normal | strict] :

none

the input is not validated

normal

the input must meet the structural rules for the file format;
the input must meet the minimum rule set defined by the reader schema

strict

the input must meet the structural rules for the file format;
the input must meet the maximum rule set defined by the reader schema, all fields must have values

showAllTags= [true | false]

show empty tags for all attributes that did not have values

forceValid= [true | false] :

true

force writer to meet the output standard when required user content is not provided;
for ISO metadata the nilReason=”missing” attribute is added to tags of missing required elements and sections;
for FGDC metadata a value of “missing” is substituted for missing element values, missing required sections will force an ERROR condition

false

missing required user content will cause ERROR condition

format= [auto | plain | json | xml] :

auto

content-type is set according to the writer;
if a writer was not specified the content-type will be set to ‘text/plain’;
if validation errors prevent the writer from generating a return, messages will be returned as ‘text/plain’;
if error messages are returned from the writer, a wrapper will be added with the content-type set according to the writer

plain

content-type=”text/plain”;
return mdTranslator results in plain text;
if validation or translator messages are detected, only the messages will be returned

json

content-type=”application/json”
results are placed in a JSON wrapper

xml

content-type=”application/xml”;
results are placed in an XML wrapper

Translator Return Object

The mdTranslator returns a JSON hash with all parameters used for the translation, messages generated during the translation, and the result of the translation. Several additional elements are added by the API and are so identified in the following table.

success (Boolean) added by the API

Success of the translation. ‘true’ if no ERROR messages were generated by the mdTranslator during parsing, reading of the input file, or writing to the requested format.

readerStructureStatus (enumerated) [ ‘OK’ | ‘NOTICE’ | ‘WARNING’ | ‘ERROR’ ] added by the API

Level of most severe message(s) returned by the translator during parsing and evaluation of the input file.
‘OK’ indicates no messages were generated.

readerStructureMessages (array of strings)

Messages return during parsing and evaluation of the input file.

readerValidationStatus (enumerated) [ ‘OK’ | ‘NOTICE’ | ‘WARNING’ | ‘ERROR’ ] added by the API

Level of most severe message(s) returned by the translator during validation of the input file’s schema. Note this step only applies to input files in the mdJson format.
‘OK’ indicates no messages were generated.

readerValidationMessages (array of strings)

Messages return during schema validation of the input file.

readerExecutionStatus (enumerated) [ ‘OK’ | ‘NOTICE’ | ‘WARNING’ | ‘ERROR’ ] added by the API

Level of most severe message(s) returned by the translator during reading of the input file into the translator’s internal format.
‘OK’ indicates no messages were generated.

readerExecutionMessages (array of strings)

Messages return during reading the input file into the translator’s internal format.

writerStatus (enumerated) [ ‘OK’ | ‘NOTICE’ | ‘WARNING’ | ‘ERROR’ ] added by the API

Level of most severe message(s) returned by the translator during writing the metadata into the requested format.
‘OK’ indicates no messages were generated.

writerMessages (array of strings)

Messages return during writing the metadata into the requested format.

readerRequested (string)

Name of the reader selected to read the input file.

readerVersionRequested (string)

Version of the reader selected to read the input file. Note this applies only to the mdJson reader.

readerVersionUsed (string)

Version of the reader used to read the input file.

writerRequested (string)

Name of the writer selected to generate the output metadata file.

writerVersion (string)

Version of the writer used to generate the output metadata file.

writerOutputFormat (enumerated) [ xml | json | html ]

Format of the output metadata file.

writerForceValid (Boolean) [ true | false ]

‘true’ if the user requested missing required elements to be marked as ‘missing’ so that the output metadata record meets the published standard.

writerShowTags (Boolean) [ true | false ]

‘true’ if the user requested missing elements to be represented by empty tags.

writerCSSlink (string)

A link to a CSS file to be added to the HTML writer header for personalizing HTML output.

writerMissingIdCount (string)

Next ID number the translator will use when the user has not provided an ID for elements that require IDs.

translatorVersion (string)

Version of the mdTranslator used to generate this return.

writerOutput (string)

The returned metadata record. The string may be in XML, JSON, or HTML format as identified by writerOutputFormat (see above).