====== 3DM Publisher Admin API ===== This document describes the Admin 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''. ===== Model: Resource ===== A ''Resource'' models a physical resource, or a logical resource with children (a resource group). Properties: ^ Property ^ Required ^ Type ^ Description ^ | id | * | number | Unique identifier for this resource. | | name | * | string | User-friendly name of the resource. | | description | | string | Resource description | | file | * | string | File system path to the main file of the resource. | | type | * | string | Resource type (extension of the file). | | thumbnail_image | | string | Resource thumbnail. | | tags | string | | Resource tags (json array serialized to a string) | | is_basemap | | number | Resource is a basemap? (1 is true, 0 is false) | | is_dem | | number | Resource is a DEM? (1 is true, 0 is false) | | is_lref | | number | Resource is a Linear Reference? (1 is true, 0 is false) | | resource_metadata | | Array | Resource metadata fields | | resource_link | | Array | Child resource links | Resource Type is defined by: * Resource Type (resource property) * Resource Content Type (resource metadata field) The most-used Resource Types: ^ Resource ^ Resource Type ^ Resource Content Type ^ | Vector Data (ovf) | ovf | - | | Vector Data (ovt) | ovt | - | | Vector Data (odb) | odb | - | | Image (omi) | omi | - | | Image (otm) | otm | - | | Point cloud (opc) | opc | - | | Point cloud (3dtiles) | 3dtiles | pointcloud | | Mapping Resource (mobile) | omr | - | | Mapping Resource (oblique) | omr | oblique | | Mapping Resource (aerial) | omr | uas | | ... | | | 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 ===== Model: ResourceMetadata ===== ^ Property ^ Type ^ Description ^ | name | string | The metadata name | | value | string | The metadata value | ===== Model: ResourceLink ===== ^ Property ^ Type ^ Description ^ | child_resource | Resource | The child resource (only ''id'' field is required). | ===== How to Send Requests ===== The information required for a basic request can be summarized as: * API Route * HTTP Method * Access Token (optional) * Query arguments (optional) * Request body (optional) ==== Default Interface ==== 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. ==== Post-only Interface ==== * HTTP Header: ''Content-Type: plain/text;'' * HTTP URL: ''POST'' ''[Server URL]''/'''' * 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). ===== Operation: Login ===== === Request === ''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. === Response (http 200) === { "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 } ===== Operation: Create Resource ===== === Request === ''POST'' ''/api/3/resource'' { "name": "test", "file": "test" } Fields: see [[#model: resource|Resource]] === Response (http 200) === { "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 } ===== Operation: Update Resource ===== === Request === ''POST'' ''/api/3/resource/151'' { "name": "BEGE MM06 test" } Fields: see [[#model: resource|Resource]] === Response (http 204) === //No content// ===== Operation: Create Resource Group ===== === Request === ''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 [[#model: resource|Resource]] ''Resource Type'' of linked Child Resources must be compatible with the ''Resource Group Type''. === Response (http 200) === { "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" } ] } ===== Operation: Update Resource Group ===== === Request === ''POST'' ''/api/3/resource/[resourceId]'' { "_http_envelope_": true, "access_token": "dZGgBzkuL8UeaQsP", "body": { "resource_link": [ { "child_resource": { "id": 15 } }, { "child_resource": { "id": 157 } } ] }, "method": "POST" } === Response (http 204) === //No content// ===== Operation: Resource Reload ===== === Request === ''GET'' ''/api/3/resource/[resourceId]/refresh'' === Response (http 204) === //No content// ===== Operation: Reload Server Configuration ====== === Request === ''GET'' ''/api/3/reload'' === Response (http 204) === //No content//