3DM Publisher Admin API

This document (partially) describes the API interface of the 3DM Publisher.

• Model Objects:
  • Resource
  • ResourceLink
  • ResourceMetadata

• It describes API routes that are relevant to managing Resource management.
• The API uses JSON as an interchange format.
• The API routes are relative to the Server Root Location.

A Resource models a physical resource, or a logical resource with children (a resource group).

Properties:

Resource Type is defined by:

• Resource Type (resource property)
• Resource Content Type (resource metadata field)

The most-used Resource Types:

Possible values for Resource status:

• ready- File is ready for use.
• missing - File was not found on the filesystem.

The thumbnail_image can be a base64-encoded JPEG image on Create or Update. On Read, the field will be provided as a URL relative to the Server Root Location.

A Resource Group is also just a Resource object.
It has the following defining characteristics:

• Resource file set to file.omp (for Mapping Resource) or file.ogp (for all other types).
• Resource type set to omp (for Mapping Resource) or ogp (for all other types).
• Resource group_child_type metadata field set to the child resource type
• Resource group_child_content_type metadata field set to the child resource content_type

The information required for a basic request can be summarized as:

• API Route
• HTTP Method
• Access Token (optional)
• Query arguments (optional)
• Request body (optional)

The default way to make a request is:

• HTTP Header: Content-Type: application/json;
• HTTP URL: [HTTP Method] [Server URL]/[API Route]?[Query arguments]
• HTTP Body: [Request body]

The access token is provided using the “access_token” query argument.

• HTTP Header: Content-Type: plain/text;
• HTTP URL: POST [Server URL]/<API Route>
• HTTP Body:

  {
      "_http_envelope_": true,
      "access_token": "xxx",
      "method": [HTTP Method],
      "query": {
          [Query arguments]
      },
      "body": {
          [Request body]
      }
  }

The access token is provided in the post body “access_token” field.

This method has the advantage of:

• Not triggering a pre-flight request in the browser, when making a cross-domain request.
• The Authorization Token is not a part of the URL so is less likely to be logged (more secure).

The Login operation creates a session that is valid for the next 900 seconds. Every time you send a request to the server, the session will again stay open for 900 seconds. When you are inactive for that duration, the session will be closed on the server side and be invalid from that point on.

If the server you are connecting to has “Access Providers” and you have a valid WKT access token for one of these providers, you can use that token for login as well. Leave the password field empty and format the username in the following way : [<code>]<accessToken>.

POST /api/3/login

{
    "username": "xxx",
    "password": "xxx",
    "publicationName": "xxx",
}

Fields:

• username - The username
• password - The password
• publicationName - For a non-admin login, this must be an existing publication name.

{
    "identifier": "6tOfZLBtPxP4xgA3",
    "created_at": "2024-11-25 15:44:48",
    "expires_at": "2024-11-25 15:59:48",
    "version": "24.4.0",
    "versionDate": "2024.11.22",
    "editingAllowed": false
}

POST /api/3/resource

{
    "name": "test",
    "file": "test"
}

Fields: see Resource

{
    "id": 199,
    "name": "test",
    "storage_space": {
        "id": 1
    },
    "file": "test",
    "type": "",
    "created_at": "2024-11-27 09:29:37",
    "modified_at": "2024-11-27 09:29:37",
    "refreshed_at": "2024-11-27 09:29:37",
    "status": "missing",
    "tags": "[]",
    "is_basemap": 0,
    "is_dem": 0,
    "is_lref": 0
}

POST /api/3/resource/151

{
    "name": "BEGE MM06 test"
}

Fields: see Resource

No content

POST /api/3/resource

{
    "name": "Test",
    "file": "file.omp",
    "type": "omp",
    "tags": "[]",
    "resource_metadata": [
        {
            "name": "collection_start",
            "value": "2024-11-27"
        },
        {
            "name": "collection_stop",
            "value": "2024-11-28"
        },
        {
            "name": "group_child_type",
            "value": "omr"
        },
        {
            "name": "group_child_content_type",
            "value": "oblique"
        }
    ],
    "resource_link": [
        {
            "child_resource": {
                "id": 15
            }
        },
        {
            "child_resource": {
                "id": 157
            }
        }
    ]
}

Fields: see Resource

Resource Type of linked Child Resources must be compatible with the Resource Group Type.

{
    "id": 200,
    "name": "Test",
    "storage_space": {
        "id": 1
    },
    "file": "file.omp",
    "type": "omp",
    "created_at": "2024-11-27 09:32:57",
    "modified_at": "2024-11-27 09:32:57",
    "refreshed_at": "2024-11-27 09:32:57",
    "status": "ready",
    "tags": "[]",
    "is_basemap": 0,
    "is_dem": 0,
    "is_lref": 0,
    "is_wfs": 0,
    "is_wms": 0,
    "resource_metadata": [
        {
            "name": "group_child_type",
            "value": "omr"
        },
        {
            "name": "collection_stop",
            "value": "2024-11-28"
        },
        {
            "name": "group_child_content_type",
            "value": ""
        },
        {
            "name": "collection_start",
            "value": "2024-11-27"
        }
    ]
}

POST /api/3/resource/[resourceId]

{
    "resource_link": [
        {
            "child_resource": {
                "id": 15
            }
        },
        {
            "child_resource": {
                "id": 157
            }
        }
    ]
}

No content

This operation will check if a resource exists on disk and update dynamic fields and metadata.

• For a resource:
  • Update num_bytes
  • Update status
  • Update resource_metadata when the file exists.
• For a resource group:
  • Update resource_metadata by merging metadata of the child resources.

GET /api/3/resource/[resourceId]/refresh

No content

This operation will instruct the server to reload the following configuration files from disk :

• configuration.ini
• config/resource.xml
• config/user.xml
• config/usergroup.xml
• publications/*
• bookmarks/*
• accessprovider/*

GET /api/3/reload

No content