UrlContext

Introduction

The UrlContext API allows the user to get context information about any given URL.

This can be useful to determine whether a URL is related to a linkable entity or whether the user is allowed to access it.

Depending on the resolved type, context information are provided in a consistent structure.

Structure

The structure of each URL Context is exactly the same. Whether all information is present depends on the type.

Key	Type	Description
key *	string	The provided URL.
type *	string	The type of the URL Context.
static_url *	string	The resolved static (never changing) URL.
url *	string	The resolved URL.
provide_information*	boolean	Whether additional information is provided.
title	string	The resolved title.
description	string	The resolved description (HTML).
icon_name	string	The resolved Icon name.
image_url	string	The resolved preview image URL.
data	array	Additional context data based on type.

Keys with * are always present in the URL Context.

Types

generic

The context for a external URL.

We currently don't provide information for this context type but plan to get title, description and image_url from the Open Graph data of the website.

internal

The context for a internal URL (e.g. /infoboard) always provides the relative URL and allows to differentiate internal from external (generic) URLs. It also includes title and icon_name information for the URL when the user is allowed to view it.

linkableEntity

The context for a linkable entity (e.g. Form) provides the "readable" URL for the entity. It also includes title, description, icon_name and image_url information for the entity when the user is allowed to view it.

fileContentEntity

The context for a file content entity (e.g. FilemanagerFile) provides the URL to show the file content of the entity. It also includes title, description, icon_name and image_url information for the entity when the user is allowed to view it. The data key also includes information about the filename, extension, mime_type, size and the download_url of the file.

sharedItem

The context for a SharedItem provides the "readable" URL based on the type of the SharedItem. Whether title, description, icon_name and image_url information are provided depends on the user being authorized to view the shared item.

List

List the URL Context for the desired urls.

Definition

POST /api/url-context

Request Keys

Key	Type	Default	Description
urls *	array	-	The URLs to get the context for.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/url-context', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'urls' => [
            'https://www.intratool.de/',
            '/infoboard',
            '/infoboard/eintrag/zn7m24owk63qolxryge8pj05',
            '/files/doxjzrnmgklojd154qwp8602',
            '/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a'
        ]
    ]
]);

Example Response

[
  {
    "type": "generic",
    "static_url": "https://www.intratool.de/",
    "url": "https://www.intratool.de/",
    "provide_information": false,
    "key": "https://www.intratool.de/"
  },
  {
    "type": "internal",
    "static_url": "/infoboard"",
    "url": "/infoboard"",
    "provide_information": true,
    "title": "Infoboard",
    "description": null,
    "icon_name": "nc-chat-round-content",
    "image_url": null,
    "data": {
      "route": "infoboard"
    },
    "key": "/infoboard"
  },
  {
    "type": "linkableEntity",
    "static_url": "/infoboard/eintrag/zn7m24owk63qolxryge8pj05",
    "url": "/infoboard/eintrag/zn7m24owk63qolxryge8pj05",
    "provide_information": true,
    "title": "Lorem ipsum dolor sit amet",
    "description": null,
    "icon_name": "nc-chat-round-content",
    "image_url": null,
    "data": {
      "type": "infoboardPost",
      "id": 20
    },
    "key": "/infoboard/eintrag/zn7m24owk63qolxryge8pj05"
  },
  {
    "type": "fileContentEntity",
    "static_url": "/files/doxjzrnmgklojd154qwp8602",
    "url": "/files/doxjzrnmgklojd154qwp8602",
    "provide_information": true,
    "title": "Lorem-ipsum.jpg",
    "description": "<strong>Größe:</strong> 150 KB<br><strong>Geändert:</strong> 01.09.2024 12:00",
    "icon_name": "nc-single-folded-content",
    "image_url": "/files/doxjzrnmgklojd154qwp8602",
    "data": {
      "entity_type": "filemanagerFile",
      "entity_id": 15,
      "filename": "Lorem-ipsum.jpg",
      "extension": "jpg",
      "mime_type": "image/jpeg",
      "size": 150000,
      "download_url": "/files/doxjzrnmgklojd154qwp8602?download=true"
    },
    "key": "/files/doxjzrnmgklojd154qwp8602"
  },
  {
    "type": "sharedItem",
    "static_url": "/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a",
    "url": "/handbuch/lorem-ipsum/#lorem-ipsum-dolor-sit-amet-consectetur-adipiscing-elit",
    "provide_information": true,
    "title": "Lorem ipsum dolor sit amet, consectetur...",
    "description": "<p><strong>Erstellt von:</strong> intratool Service</p><p><strong>Geändert:</strong> 01.01.2024 12:00</p><p></p><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>",
    "icon_name": "nc-file-article",
    "image_url": null,
    "data": {
      "type": "manualEntry",
      "targetable_type": "manualEntry",
      "targetable_id": 10,
      "targetable_deleted": false
    },
    "key": "/geteilte-inhalte/9ae0e631-37b4-4ef0-8a26-1526f329098a"
  }
]