Geoscience Object API release notes

Supported API versions

The following Geoscience Object API versions are currently supported:

• 1.0.0

Changes

1.9.0

Removal of organization-level putData operation

The putData endpoint (/geoscience-object/orgs/{org_id}/data) was deprecated in 1.3.0 and is no longer part the API. Any data previously uploaded to this endpoint will continue to be available via an object that references it. New data must be uploaded to putDataInWorkspace (/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/data)

1.8.0

Deleting and restoring objects

This release adds endpoints to delete and restore objects. Objects that are deleted through these endpoints are "soft deleted". This means that they are excluded from regular queries, but can be retrieved and restored as needed.

An object can be soft deleted using the following endpoints:

• DELETE /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}
• DELETE /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/{object_path}

An object can be restored using the following endpoint:

• POST /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}?deleted=false

The object will be restored to its original name and path. In the case of a conflict, the name will be appended with a (1). This number will be increased in the case of any subsequent conflicts.

Soft deleted objects can be downloaded and listed using the following endpoints:

• GET /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}?deleted=true
• GET /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects?deleted=true

1.7.0

Strict enforcement of JSON Schema number types

Newly uploaded objects cannot contain non-finite numbers in any number field. Non-finite numbers include Infinity, -Infinity, and NaN.

The JSON specification does not include non-finite numbers. The service previously accepted such values as a side-effect of parsing JSON objects to Python internally. Such values would be returned as null.

This behaviour has been removed. A validation error is raised instead.

1.6.0

Name case now treated insensitively

The service will no longer be case-sensitive but will remain case preserving. Previously you were able to upload two objects with the names, object.json and Object.json, and they would be considered distinct. In this release, these objects would be considered the same, and you would receive a name conflict error.

1.5.0

Enforcement of Workspace role-based access

Previously, workspace membership (i.e. the Viewer role) was sufficient to perform any operations. With this release, creating/updating objects and uploading data to a workspace now require that you have the Editor or Owner role.

The organization-level data upload endpoint (deprecated in 1.3.0) is unaffected.

Requests that lack the required role will be met with a 403 response:

{
    "your_role": "viewer",
    "permitted_roles": [
        "editor",
        "owner"
    ],
    "status": 403,
    "title": "Insufficient Role.",
    "detail": "Access to this resource is forbidden due to an insufficient role.",
    "type": "https://seequent.com/error-codes/geoscienceobject/auth/insufficient-role"
}

1.3.0

Deprecation of organization-level data

This release marks the putData endpoint (/geoscience-object/orgs/{org_id}/data) as deprecated. This will be removed from the API in September 2024.

You are encouraged to move to workspace-level data, using the new /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/data endpoint.

Workspace-level data upload

The new /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/data endpoint functions similarly to its organization-level predecessor, but with some notable changes to the overall API. Primarily, the SHA256 or UUID previously used as an id is now a name field. You can continue to use this name as they had before for identifying and de-duplicating blobs. As an interim step, the data links provided when uploading or downloading an object may contain data from the organization or workspace layers, therefore that part of the JSON body should be interpreted differently. The following snippets are links to equivalent data blobs.

From the organization:

{
    "id": "b19ca2ef5c7e69cb163746d1d4e869d88975613dbad2464a927b37b12c4e1ee9",
    "download_url": "<download link>"
}

Or from the workspace:

{
    "id": "<uuid>",
    "name": "b19ca2ef5c7e69cb163746d1d4e869d88975613dbad2464a927b37b12c4e1ee9",
    "download_url": "<download link>"
}

In short, if there is a name field, use that, otherwise defer to the id field.

1.1.0

Filtering and sorting support has been added to the "list objects" API.

There are a number of known filters as denoted in the API spec, e.g. schema_id or created_at. The following filter operators are supported:

operator	name	example
eq	equal to. If no other operator is supplied, this will be used by default*	author=eq:3b1bf5e2-cac0-11ee-ad21-00155d874352
neq	not equal to.	author=neq:3b1bf5e2-cac0-11ee-ad21-00155d874352
in	value is in a list of filter values	object_name=in:first,second
nin	value is not in a list of filter values	object_name=nin:bad,other
like	use a * wildcard to match string values like the filter value. Similar to SQL's LIKE operator	schema_id=like:*variogram*
ilike	case insensitive version of the like operator above	schema_id=ilike:*VaRiOgRaM*
nlike / nilike	negated versions of like and ilike	object_name=nlike:badPrefix*
lt / lte	less that / less that or equal to	created_at=lte:2023-03-10T22:56:53Z
gt / gte	greater than / greater than or equal to	created_at=gt:gte:2023-03-10T22:56:53Z

*eq is the default operator for all fields except object_name. For backwards compatibility, object_name without an operator functions as a prefix filter (i.e. it matches against names that start with the given filter value).

The API also exposes arbitrary filters. Any filter prefixed with object can be used to filter on the object metadata itself. Unrecognised fields will be ignored.

An example query to find all variograms with a data_variance property under 0.3:

GET /objects?object.data_variance=lt:0.3&schema_id=like:*variogram*

Results can be sorted by providing the order_by query parameter with a comma separated list of field names. Objects are sorted by these fields in order.

For example, ?order_by=created_at,desc:object.data_variance will order by created_at first, then by object.data_variance in descending order. A field without asc or desc will be default to ascending order.

1.0.0

"path" query and list endpoint response

This release involves a change to the list objects endpoint.

• The path query parameter will no longer be accepted.
• The response will not list objects in a hierarchical format, but will return a flat list of objects regardless of path.

For example, consider the following objects:

/dira/dirb/object1.json
/dira/dirb/dirc/object2.json
/dira/dirb/dird/object3.json

Before this release, listed objects at the path /dira/dirb/ would get the following response:

{
    "path": "/dira/dirb/",
    "results": [
        {
            "name": "object1.json",
            "object_id": "<some_uuid>",
            ...
        },
        {
            "name": "dirc",
            "links": ...
        },
        {
            "name": "dird",
            "links": ...
        }
    ]
}

With this release, the top level path field has been removed and will list objects at any level. The objects themselves will now contain a name and path field.

{
    "objects": [
        {
            "name": "object1.json",
            "path": "/dira/dirb/",
            "object_id": "<some_uuid>",
            ...
        },
        {
            "name": "object2.json",
            "path": "/dira/dirb/dirc",
            "object_id": "<some_uuid>",
            ...
        },
        {
            "name": "object3.json",
            "path": "/dira/dirb/dird/",
            "object_id": "<some_uuid>",
            ...
        }
    ]
}

Object version ID

The string format of the version_id field has changed from an ISO timestamp to the equivalent as a unix timestamp (in nanoseconds).

The current object upload and download endpoint return values have changed:

{
-   "version_id": "2023-08-30T23:14:50.2891923Z",
+   "version_id": "1693437237147318966",
    "created_at": "2023-08-30T23:14:50Z",
    ...
}

Note that the created_at field should be preferred when discerning creation time. This field is an ISO8601 datetime and remains unchanged with this release.

Source field

As an extra measure of ensuring that geoscience data is sourced accurately, we need to change where the source is defined. The source field has been removed from the available filters on the "list objects" endpoint.

Fetching data for an object

The data related to an object is now returned in the links section of an object response. The response body for the following are all identical and contain such links:

• GET /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}
• GET /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path{object_path}
• POST /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}
• POST /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path{object_path}

These links are pre-signed URLs, which can be used to retrieve the data from storage directly. The URLs are only valid for a short period of time. Simply repeat one of the above requests to obtain a new, valid URL.

The links in the response now contains data, which is a list of objects, much like the former POST /data response. See the OpenAPI schema for more details.

Updating an object

A new endpoint has been added to support updating an object. A valid request will post a new version of the object for that given object UUID, effectively updating the object.

• POST /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}

Checking which objects have changed

A new endpoint has been added to support checking which objects have changed. This allows clients to supply a list of object UUIDs which the service will check and return the latest version_id for.

• PATCH /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects

Verify the latest version of an object

The endpoint to fetch an object by UUID has been updated to allow a client to supply a version_id (via the If-None-Match header value) and allow the service to indicate whether the object has not been modified (version matches the latest version of the object) or return the latest version of the object.