# 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](#types), context information are provided in a consistent [structure](#structure).

## Structure

The structure of each URL Context is exactly the same. Whether all information is present depends on the [type](#types).

| Key                     | Type    | Description                                                                  |
| ----------------------- | ------- | ---------------------------------------------------------------------------- |
| `key` \*                | string  | The provided URL.                                                            |
| `type` \*               | string  | The [type](#types) 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](https://docs.api.intratool.de/api-reference/icons) name. |
| `image_url`             | string  | The resolved preview image URL.                                              |
| `data`                  | array   | Additional context data based on [type](#types).                             |

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](https://docs.api.intratool.de/api-reference/forms/forms)) 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](https://docs.api.intratool.de/api-reference/filemanager/filemanager-files)) 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](https://docs.api.intratool.de/api-reference/shared-items) 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**

<mark style="color:yellow;">`POST`</mark> `/api/url-context`

**Request Keys**

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

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```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'
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "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"
  }
]
```