Stages

Preview API

This endpoint is marked as a preview API. Preview APIs may be unstable within the preview period: they may change without notice. You must set the header API-Preview: opt-in to opt into using this endpoint.

Introduction

This guide will walk you through the process of fetching a list of available geoscience object stages, and updating them in Evo.

Stages represent different phases in the lifecycle of a geoscience object, such as "Approved", "Experimental", and "In Review". These are important for managing and tracking the progress of geoscience objects within an organisation.

Endpoints

• GET /geoscience-object/orgs/{org_id}/stages
• PATCH /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}/metadata

List stages

This endpoint allows you to fetch a list of stages for geoscience objects. The response will include all of the available stages for the specified organisation.

This endpoint does not include any request parameters. The only variable component of this endpoint is the requested organisation, set through the {org_id}.

Example request URL:

GET /geoscience-object/orgs/{org_id}/stages

Response

The response of this endpoint is a JSON object containing a list of the requested organisation's available stages.

Example:

{
  "stages": [
    {
      "stage_id": "2b8847c9-b2b0-4d89-9f3d-20d8a113c1da",
      "name": "Approved"
    },
    {
      "stage_id": "8a3acb86-babe-4eed-958b-d42efab36ed4",
      "name": "Experimental"
    },
    {
      "stage_id": "2fec273f-c807-4a01-9177-338c36237bff",
      "name": "In Review"
    },
    {
      "stage_id": "0321221c-190b-47b9-bc5a-50684c912880",
      "name": "Peer Review"
    },
    {
      "stage_id": "985271f4-0f13-4018-ba98-00ae2dd0cb2b",
      "name": "Preliminary Update"
    },
    {
      "stage_id": "413c4fd4-11c3-4d87-926f-ca317eda8833",
      "name": "Resource Ready"
    }
  ]
}

Field descriptions

• stage_id: Unique identifier for the stage.
• name: Name of the stage.

Set object stage

This endpoint allows you to update the stage metadata for a given geoscience object. The response will contain no content.

This endpoint must include the stage_id of the stage that the object is being updated to, in the request body. If the stage id is set to null, then the stage metadata will be removed from the object version. This endpoint also includes an optional version request parameter set through the version_id, to specify the object version you are wanting to update. If this is not specified then the latest version will be used. The other variable components of this endpoint are the requested organisation, workspace, and object, set through the {org_id}, {workspace_id}, and {object_id}, respectively.

Example request URL:

PATCH /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}/metadata?version_id=1706583776404684724"

Example request body:

{
  "stage_id": "25ca08d5-e85c-4d81-adeb-a87db15ccd88"
}

Response

The response of this endpoint is a 204 No Content status code.

Summary

1. To list all stages, make a GET request to the /geoscience-object/orgs/{org_id}/stages endpoint.
2. The response will include a list of the requested organisation's available stages.
3. To update the stage of a geoscience object, make a request to the /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/{object_id}/metadata endpoint, with the stage_id included in the request body and an optional version_id included in the request parameter.
4. The response will be a 204 No Content status code.