====== 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''. ===== 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 ===== === Discussion === 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 : ''[]''. === 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]'' { "resource_link": [ { "child_resource": { "id": 15 } }, { "child_resource": { "id": 157 } } ] } === Response (http 204) === //No content// ===== Operation: Resource Reload ===== === Discussion === 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. === Request === ''GET'' ''/api/3/resource/[resourceId]/refresh'' === Response (http 204) === //No content// ===== Operation: Reload Server Configuration ====== === Discussion === 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/*'' === Request === ''GET'' ''/api/3/reload'' === Response (http 204) === //No content//