Catalog Operations

In this documentation and examples, the service as described in the previous section on model resource naming is assumed to be https://www.example.com/ermrest.

Service Ad Retrieval

Outside of any catalog context, the service itself offers a brief advertisement of its capability.

The GET method is used to retrieve the service advertisement. This request also serves as a basic health-check of the ERMrest service:

GET /ermrest/ HTTP/1.1
Host: www.example.com

On success, this request yields the service advertisement:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "version": "0.2.0",
  "features": {
    ...
  }
}

Typical error response codes include:

  • 400 Bad Request (on legacy versions lacking this feature)
  • 503 Service Unavailable (if basic service health-check is failing)

The "version" field is the ermrest Python package version as installed. The "features" field is where ERMrest may advertise software features added in subsequent revisions. This allows fine-grained feature detection by clients concerned with exploiting new features, when available, but falling back to simpler access modes if accessing older catalogs.

Known feature flags at time of writing of this document:

  • trs: Service supports the trs(RID) projection functions to retrieve row-level access rights.
  • tcrs: Service supports the tcrs(RID) projection functions to retrieve row-level, per-column access rights.
  • history_control: Service supports tag:isrd.isi.edu:2020,history-capture table annotation to disable history capture.
  • implicit_fkey_index: Service will produce indexes for compound foreign keys to allow index-based joins on these reference patterns.

Generally, absence of a feature flag means the service is running older software which predates the release of the feature. A flag will be present with boolean value true to advertise presence of a feature. Specific flags may be documented with other advertisement values in the future, i.e. to indicate runtime status of a feature which can be disabled selectively by the administrator.

Catalog Creation

The POST method is used to create an empty catalog:

POST /ermrest/catalog HTTP/1.1
Host: www.example.com

On success, this request yields the new catalog identifier, e.g. 42 in this example:

HTTP/1.1 201 Created
Location: /ermrest/catalog/42
Content-Type: application/json

{
  "id": "42",
  "snaptime": "2PX-WS30-E58W"
}

Typical error response codes include:

  • 404 Not Found
  • 403 Forbidden
  • 401 Unauthorized

Catalog Retrieval

The GET method is used to get a short description of a catalog:

GET /ermrest/catalog/42 HTTP/1.1
Host: www.example.com

On success, this request yields a description:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "42",
  "annotations": {
    "tag:isrd.isi.edu,2018:example": {"value": "my example annotation"}
  },
  "snaptime": "2PX-WS30-E58W",
  "features": {
     ...
  }
}

The "features" field is previously described in the Service Ad Retrieval request.

Typical error response codes include:

  • 404 Not Found
  • 403 Forbidden
  • 401 Unauthorized

Catalog Deletion

The DELETE method is used to delete a catalog and all its content:

DELETE /ermrest/catalog/42 HTTP/1.1
Host: www.example.com

On success, this request yields a description:

HTTP/1.1 204 No Content

Typical error response codes include:

  • 404 Not Found
  • 403 Forbidden
  • 401 Unauthorized