API docs by Redocly

CoMET API (v2)

Download OpenAPI specification:Download

Collection Manager Support Team: ncei.collection-manager.support@noaa.gov URL: /docucomp
CoMET/DSMQ User Guide

Introduction

CoMET was created by the National Centers for Environmental Information (NCEI) to be NOAA’s comprehensive and easy to use collection metadata creation and editing tool. It allows users to create ISO compliant metadata, can support NCEI collection metadata template, and is a gateway to publishing metadata to OneStop.

ISO

For more information on the ISO Standard 19115-2, please visit this documentation link.

OpenAPI Specification

This API is documented in OpenAPI format and is displayed using ReDoc. In addition to standard OpenAPI syntax, ReDoc uses a few vendor extensions.

Transformations

Export/Read and Import endpoints support use of the transform query parameter. The following transform parameters are supported.

  • Import: These transformations accept a document format and convert it to CoMET Format, which is stored in the database.
    • convert-iso19115-2-to-comet imports ISO 19115-2 XML saves as CoMET format.
  • Read/Export: These transforms retrieve CoMET format metadata from the database and return a document in the response body.
    • convert-comet-to-iso19115-2 exports ISO 19115-2 as an XML document with xlinks resolved
    • convert-comet-to-iso19115-2-unresolved exports ISO 19115-2 as an XML document with xlinks unresolved
    • convert-iso19115-2-to-landingPage transforms ISO 19115-2 XML to NCEI's Landing Page as an HTML document
    • convert-iso19115-2-to-text transforms ISO 19115-2 XML to CoMET Format plain text as an HTML document
    • convert-iso19115-2-to-cswRubric transforms ISO 19115-2 to the CSW Readiness Report as an HTML document
    • convert-iso19115-2-to-doiRubric transforms ISO 19115-2 to the DOI Readiness Report as an HTML document
    • convert-iso19115-2-to-components transforms ISO 19115-2 to a Component Analysis Report as an HTML document

Authentication

Users must first establish a user session in order to create, read/view, update, or delete metadata. Sessions are established by sending login credentials via an HTTP request to the login URL. The server will create a cookie that contains an API Key (JSESSIONID) that authorizes each request. The cookie must be sent with each request and is valid so long as the session stays alive.

Login Requirements:

  • Users must have a @noaa.gov email account.
  • User must log into the UI at least once for their account and default record group to be generated.

HTTPCookie

Security Scheme Type: API Key
Cookie parameter name: JSESSIONID

Login

Users must first establish a user session in order to create, read/view, update, or delete metadata. Sessions are established by sending login credentials via an HTTP request to the login URL. The server will create a cookie that contains an API Key (JSESSIONID) that authorizes each request. The cookie must be sent with each request and is valid so long as the session stays alive.

Login

Request Body schema: application/x-www-form-urlencoded
username
string
password
string

Responses

Request samples 

# This script saves your apiKey (JSESSIONID) to a cookie file on disk. This file, cookie.txt, is sent in other examples in this documentation 

curl -X 'POST' \
'https://data.noaa.gov/cedit/login/wsLogin' \
-H 'accept: */*' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'username=your.username' -d 'password=yourPassword'  \
--cookie-jar cookies.txt

Metadata Operations

Create, Update, Delete, and Validate Metadata

CoMET/DSMQ User Manual

Create/Import

Create or import an ISO metadata file into CoMET. The default data expect is CoMET Format XML. To import ISO 19115-2 XML use the transform query parameter.

Authorizations:
HTTPCookie
query Parameters
recordGroup
required
string
Example: recordGroup=Comet%20Training

The record group, which may represent a Web Accessible Folder (WAF) that contains 1 or more ISO metadata records stored in CoMET. If your record group name includes reserved, unsafe, or other characters not supported in URLs; they will need to be encoded. For example, a record group with the name My/Record/Group/, would need to be encoded as My%2FRecord%2FGroup%2F

description
required
string

Title of the record in the CoMET database

transform
required
string
Value: "convert-iso19115-2-to-comet"
Example: transform=convert-iso19115-2-to-comet

Type of transformation to apply to the metadata record. Please review the section title Transformations for more detail.

uuid
string

Universally Unique Identifier. For import, Use this query parameter if you create your own UUIDs. Otherwise, the system will generate one for you.

editState
string
Enum: "DRAFT" "COMPLETED" "PUBLISH" "PUBLISH_PROCESSING" "IN_REVIEW" "APPROVED" "UNPUBLISHED" "UNRESOLVED" "INVALID"
Example: editState=APPROVED

Status of record.

format
string
Enum: "xml" "json" "text"
Example: format=xml

Response format. This parameter does not change the format of metadata documents/data. Use the transform parameter instead

Request Body schema: application/xml

Accepts XML document in Comet Format XML or ISO 19915-2 XML. Default Comet Format XML. To change, use the transform parameter

One of
object

Responses

Request samples

Content type
application/xml
Loading...

Response samples

Content type
{
  • "message": "success",
  • "status": 200,
  • "uuid": "1d2b290b-abe9-479b-8179-a5dd819bdf90"
}

Read/Export

Read/Export Metadata. The default schema returned is CoMET Format XML. To return ISO 19115-2 XML document, you must use transform query parameter. Other document and reports exports are support by using the transform parameter.

Authorizations:
HTTPCookie
path Parameters
uuid
required
string

Universally Unique Identifier. Use this query parameter if you create your own UUIDs. Otherwise, the system will generate one for you.

query Parameters
transform
string
Enum: "convert-comet-to-iso19115-2" "convert-iso19115-2-to-landingPage" "convert-iso19115-2-to-text" "convert-iso19115-2-to-rubricV2" "convert-iso19115-2-to-cswRubric" "convert-iso19115-2-to-doiRubric" "convert-iso19115-2-to-components"
Example: transform=convert-comet-to-iso19115-2

Type of transformation to apply to the metadata record. Please review the section title Transformations for more detail.

format
string
Enum: "xml" "json" "text"
Example: format=xml

Response format. This parameter does not change the format of metadata documents/data. Use the transform parameter instead

Responses

Request samples 

curl --cookie cookies.txt "https://data.noaa.gov/cedit/metadata/{your uuid}" > {your fileName}.xml

Response samples

Content type
application/xml
Loading...

Delete

Delete Metadata record

Authorizations:
HTTPCookie
path Parameters
uuid
required
string

Universally Unique Identifier. Use this query parameter if you create your own UUIDs. Otherwise, the system will generate one for you.

query Parameters
format
string
Enum: "xml" "json" "text"
Example: format=xml

Response format. This parameter does not change the format of metadata documents/data. Use the transform parameter instead

Responses

Request samples 

curl --cookie cookies.txt -X DELETE "https://data.noaa.gov/cedit/metadata/{your uuid}"

Response samples

Content type
{
  • "message": "success",
  • "status": 200
}

Update

Authorizations:
HTTPCookie
path Parameters
uuid
required
string

Universally Unique Identifier. Use this query parameter if you create your own UUIDs. Otherwise, the system will generate one for you.

query Parameters
description
string

Title of the record in the CoMET database

transform
required
string
Value: "convert-iso19115-2-to-comet"
Example: transform=convert-iso19115-2-to-comet

Type of transformation to apply to the metadata record. Please review the section title Transformations for more detail.

editState
string
Enum: "DRAFT" "COMPLETED" "PUBLISH" "PUBLISH_PROCESSING" "IN_REVIEW" "APPROVED" "UNPUBLISHED" "UNRESOLVED" "INVALID"
Example: editState=APPROVED

Status of record.

format
string
Enum: "xml" "json" "text"
Example: format=xml

Response format. This parameter does not change the format of metadata documents/data. Use the transform parameter instead

Request Body schema: application/xml

Accepts XML document in Comet Format XML or ISO 19915-2 XML. Default Comet Format XML. To change, use the transform parameter

One of
object

Responses

Request samples

Content type
application/xml
Loading...

Response samples

Content type
{
  • "message": "success",
  • "status": 200,
  • "uuid": "1d2b290b-abe9-479b-8179-a5dd819bdf90"
}

Search

Authorizations:
HTTPCookie
query Parameters
recordGroup
required
string
Example: recordGroup=Comet%20Training

The record group, which may represent a Web Accessible Folder (WAF) that contains 1 or more ISO metadata records stored in CoMET. If your record group name includes reserved, unsafe, or other characters not supported in URLs; they will need to be encoded. For example, a record group with the name My/Record/Group/, would need to be encoded as My%2FRecord%2FGroup%2F

editState
string
Enum: "DRAFT" "COMPLETED" "PUBLISH" "PUBLISH_PROCESSING" "IN_REVIEW" "APPROVED" "UNPUBLISHED" "UNRESOLVED" "INVALID"
Example: editState=APPROVED

Status of record.

format
string
Enum: "xml" "json" "text"
Example: format=xml

Response format. This parameter does not change the format of metadata documents/data. Use the transform parameter instead

max
integer [ 1 .. 10000 ]
Default: 5000
Example: max=50

Maximum number of records to return

offset
integer [ 1 .. 5000 ]
Default: 1
Example: offset=50

Number of records to exclude from the responses first N items. Use with max to request a set of items. Offset is applied before the max parameter regardless of its position in the request.

since
string <date> /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
Example: since=2022-01-01T00:00:00.000Z

Return metadata records updated since this date. Requires yyyy-MM-dd format

Responses

Request samples 

curl -G "https://data.noaa.gov/cedit/metadata/search?format=json"  \
  --data-urlencode "recordGroup={your record group}" \
  --cookie cookies.txt

Response samples

Content type
{
  • "message": "success",
  • "status": 200,
  • "totalCount": 20,
  • "metadata": [
    ]
}

Validate

Requires the transform parameter set to convert-comet-to-iso19115-2 to validate a record. (?transform=convert-comet-to-iso19115-2). Other transforms will return an error.

Authorizations:
HTTPCookie
path Parameters
uuid
required
string

Universally Unique Identifier. Use this query parameter if you create your own UUIDs. Otherwise, the system will generate one for you.

query Parameters
transform
required
string
Value: "convert-comet-to-iso19115-2"
Example: transform=?transform=convert-comet-to-iso19115-2

Type of transformation to apply to the metadata record. Please review the section title Transformations for more detail.

format
string
Enum: "xml" "json" "text"
Example: format=xml

Response format. This parameter does not change the format of metadata documents/data. Use the transform parameter instead

Responses

Request samples 

curl --cookie cookies.txt "https://data.noaa.gov/cedit/metadata/validate/{your uuid}?transform=convert-comet-to-iso19115-2"

Response samples

Content type
{
  • "message": "success",
  • "status": 200
}

Record Services

Record Services currently supports validating ISO 19115-2 metadata, validating online resource links, checks to see if a resolved xlinks creates valid XML, and provides the Rubric V2 scores as a json object.

CoMET User Manual

Validate

Resolves xlinks to xml components and validates resulting document against the ISO 19115-2 standard

Authorizations:
HTTPCookie
query Parameters
filename
required
string

Filename or name of record being sent

Request Body schema: application/xml

AcceptsISO 19915-2 XML.

gmi:MI_Metadata
object

Responses

Request samples

Content type
application/xml
Loading...

Response samples

Content type
application/json
Example
{
  • "service": "isovalidatecheck",
  • "date-time": "2022-09-27T13:48:31.452Z",
  • "record": "example.xml",
  • "error_count": "0"
}

Rubric V2

Returns Rubric V2 scores as json object

Authorizations:
HTTPCookie
query Parameters
filename
required
string

Filename or name of record being sent

Request Body schema: application/xml

Accepts XML in ISO 19115-2, resolves xlinks,

gmi:MI_Metadata
object

Responses

Request samples

Content type
application/xml
Loading...

Response samples

Content type
application/json
Example
{
  • "service": "transisotorubricv2",
  • "date-time": "2022-09-27T13:48:31.452Z",
  • "record": "example.xml",
  • "error_count": "0",
  • "totals_array": [
    ],
  • "categories_array": [
    ]
}

Simple Resolve

Resolves xlinks to xml components and returns a success if XML document is created. Doesn't return errors if xlink or resulting XML isn't valid ISO 19115-2

Authorizations:
HTTPCookie
Request Body schema: application/xml

Accepts XML in ISO 19115-2 and resolves xlinks to xml components. Only responds 200 for success or 400 for failure. See Transform to get a resolved document to save.

gmi:MI_Metadata
object

Responses

Request samples

Content type
application/xml
Loading...

Response samples

Content type
application/json
Example
{
  • "statusCode": "200",
  • "statusMessage": "success"
}

Link Check

Verify online resource links within the ISO tag CI_OnlineResource are valid URLs. This API can be slow depending on the number links to be checked and the link status.

Authorizations:
HTTPCookie
Request Body schema: application/xml

Accepts ISO 19115-2 XML

gmi:MI_Metadata
object

Responses

Request samples

Content type
application/xml
Loading...

Response samples

Content type
application/json
Example
{
  • "service": "olrlinkcheck",
  • "date-time": "2022-09-27T13:48:31.452Z",
  • "record": "example.xml",
  • "error_count": "0"
}

Transform

Upload an xml document by rawxml or url and transform it to a requested format

Authorizations:
HTTPCookie
Request Body schema: application/x-www-form-urlencoded
inputLocation
string
Enum: "rawxml" "url"

Input Options: rawxml, url
rawxml - Allows you to send xml in the form using the parameter rawxml.
url - Allows you to upload xml from a url using the parameter url.

recordAction
string
Enum: "resolve" "none" "isovalidatecheck" "olrlinkcheck" "nceilandingpage" "transisotorubricv2" "transisotorubric" "transncmltorubric" "transncmltoiso" "fgdctoiso"

resolve - Resolve URL references to components. Input: 19139 schema valid XML file. Response: ISO 19115-2 XML
none - Check for well-formed XML. Input: 19139 schema valid XML file. Response: Plain Text
isovalidatecheck - Validate metadata with 19139 Schema. Input: 19139 XML file. Response: HTML
olrlinkcheck - Verify online resource links within the ISO tag CI_OnlineResource are valid URLs. Response: Plain Text
nceilandingpage - Generate the NCEI Landing page view based on a valid ISO 19115-2 XML file. Response: HTML
transisotorubricv2 - Generate v2 IMPROVED completeness assessment report. Input: 19139 schema valid XML file. Response: HTML
transisotorubric - Generate v1 completeness assessment report. Input: 19139 schema valid XML file. Response: HTML
transncmltorubric - Generate v1 completeness assessment report. Input: NetCDF XML. Response: HTML
transncmltoiso - Translate from NCML to ISO 19115-2. Input: ACDD compliant NetCDF XML. Response: ISO 19115-2 XML
fgdctoiso - Translate from FGDC to ISO 19115-2. Input: FGDC compliant XML. Response: ISO 19115-2 XML

filename
string

Name if the file uploaded. Ignored if url is used for inputLocation

url
string

URL to retrieve XML. Ignored if rawxml is used for inputLocation

rawxml
string

The XML uploaded by file. Ignored if url is used for inputLocation

Responses

Request samples 

#!/bin/bash
# Transform a file on your computer using Record Services

export CEDIT_URL="https://data.noaa.gov/recordServices/upload"

# Change this variable for different transforms, options are:
# resolve, none, isovalidatecheck, olrlinkcheck, nceilandingpage,
# transisotorubricv2, transisotorubric, transncmltorubric, transncmltoiso, and fgdctoiso
recordAction="resolve"

echo -n "Enter the filename to transform: "
read filename

curl --cookie cookies.txt \
  -L --max-redirs 1 \
  -k \
  "$CEDIT_URL" \
  -F recordAction="$recordAction" \
  -F inputLocation="file" \
  -F filename=@"$filename"