Skip to content

[HLAPI] Reminders, RSS Feeds, and Reservations #21539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 27, 2025
Merged

[HLAPI] Reminders, RSS Feeds, and Reservations #21539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ The present file will list all changes made to the project; according to the
- `approver`, `approval_followup`, `date_creation`, `date_mod`, and `date_approval` properties for the Solution schema in the High-Level API v2.1.
- `timeline_position` property for the TicketValidation, ChangeValidation and Document_Item schemas in the High-Level API v2.1.
- `date_solve`, `date_close`, and `global_validation` properties for the applicable Ticket, Change and Problem schemas in the High-Level API v2.1.
- New schemas/endpoints for Reminders, RSS Feeds, and Reservations in the High-Level API v2.1.

### Changed
- Added High-Level API version 2.1. Make sure you are pinning your requests to a specific version (Ex: `/api.php/v2.0`) if needed to exclude endpoints/properties added in later versions. See version pinning in the getting started documentation `/api.php/getting-started`.
Expand Down
347 changes: 347 additions & 0 deletions src/Glpi/Api/HL/Controller/ToolController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,347 @@
<?php

/**
* ---------------------------------------------------------------------
*
* GLPI - Gestionnaire Libre de Parc Informatique
*
* http://glpi-project.org
*
* @copyright 2015-2025 Teclib' and contributors.
* @copyright 2003-2014 by the INDEPNET Development Team.
* @licence https://www.gnu.org/licenses/gpl-3.0.html
*
* ---------------------------------------------------------------------
*
* LICENSE
*
* This file is part of GLPI.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* ---------------------------------------------------------------------
*/

namespace Glpi\Api\HL\Controller;

use CommonDBTM;
use Entity;
use Glpi\Api\HL\Doc as Doc;
use Glpi\Api\HL\Middleware\ResultFormatterMiddleware;
use Glpi\Api\HL\ResourceAccessor;
use Glpi\Api\HL\Route;
use Glpi\Api\HL\RouteVersion;
use Glpi\Http\JSONResponse;
use Glpi\Http\Request;
use Glpi\Http\Response;
use Planning;
use Reminder;
use ReservationItem;
use RSSFeed;
use User;

#[Route(path: '/Tools', tags: ['Tools'])]
final class ToolController extends AbstractController
{
public static function getRawKnownSchemas(): array
{
return [
'Reminder' => [
'x-version-introduced' => '2.1.0',
'x-itemtype' => Reminder::class,
'type' => Doc\Schema::TYPE_OBJECT,
'properties' => [
'id' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'readOnly' => true,
],
'uuid' => [
'type' => Doc\Schema::TYPE_STRING,
'pattern' => Doc\Schema::PATTERN_UUIDV4,
'readOnly' => true,
],
'name' => ['type' => Doc\Schema::TYPE_STRING],
'text' => ['type' => Doc\Schema::TYPE_STRING],
'date' => [
'type' => Doc\Schema::TYPE_STRING,
'format' => Doc\Schema::FORMAT_STRING_DATE_TIME,
],
'user' => self::getDropdownTypeSchema(class: User::class, full_schema: 'User'),
'date_begin' => [
'type' => Doc\Schema::TYPE_STRING,
'format' => Doc\Schema::FORMAT_STRING_DATE_TIME,
'x-field' => 'begin',
],
'date_end' => [
'type' => Doc\Schema::TYPE_STRING,
'format' => Doc\Schema::FORMAT_STRING_DATE_TIME,
'x-field' => 'end',
],
'is_planned' => ['type' => Doc\Schema::TYPE_BOOLEAN],
'state' => [
'type' => Doc\Schema::TYPE_INTEGER,
'enum' => [Planning::INFO, Planning::TODO, Planning::DONE],
'description' => <<<EOT
The state of the event.
- 1: Information
- 2: To do
- 3: Done
EOT,
],
'date_view_begin' => [
'type' => Doc\Schema::TYPE_STRING,
'format' => Doc\Schema::FORMAT_STRING_DATE_TIME,
'x-field' => 'begin_view_date',
],
'date_view_end' => [
'type' => Doc\Schema::TYPE_STRING,
'format' => Doc\Schema::FORMAT_STRING_DATE_TIME,
'x-field' => 'end_view_date',
],
'date_creation' => ['type' => Doc\Schema::TYPE_STRING, 'format' => Doc\Schema::FORMAT_STRING_DATE_TIME],
'date_mod' => ['type' => Doc\Schema::TYPE_STRING, 'format' => Doc\Schema::FORMAT_STRING_DATE_TIME],
],
],
'RSSFeed' => [
'x-version-introduced' => '2.1.0',
'x-itemtype' => RSSFeed::class,
'type' => Doc\Schema::TYPE_OBJECT,
'properties' => [
'id' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'readOnly' => true,
],
'comment' => ['type' => Doc\Schema::TYPE_STRING],
'url' => [
'type' => Doc\Schema::TYPE_STRING,
'required' => true,
],
'refresh_interval' => [
'type' => Doc\Schema::TYPE_INTEGER,
'description' => 'Refresh interval in seconds',
'x-field' => 'refresh_rate',
'min' => HOUR_TIMESTAMP,
'max' => DAY_TIMESTAMP,
'multipleOf' => HOUR_TIMESTAMP,
],
'max_items' => [
'type' => Doc\Schema::TYPE_INTEGER,
'description' => 'Maximum number of items to fetch',
],
'have_error' => [
'type' => Doc\Schema::TYPE_BOOLEAN,
'readOnly' => true,
'description' => 'Whether the last fetch had errors',
],
'is_active' => ['type' => Doc\Schema::TYPE_BOOLEAN],
'user' => self::getDropdownTypeSchema(class: User::class, full_schema: 'User'),
'date_creation' => ['type' => Doc\Schema::TYPE_STRING, 'format' => Doc\Schema::FORMAT_STRING_DATE_TIME],
'date_mod' => ['type' => Doc\Schema::TYPE_STRING, 'format' => Doc\Schema::FORMAT_STRING_DATE_TIME],
],
],
'ReservableItem' => [
'x-version-introduced' => '2.1.0',
'x-itemtype' => ReservationItem::class,
'type' => Doc\Schema::TYPE_OBJECT,
'properties' => [
'id' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'readOnly' => true,
],
'itemtype' => [
'type' => Doc\Schema::TYPE_STRING,
'description' => 'The itemtype of the reservable item',
],
'items_id' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'description' => 'The ID of the reservable item',
],
'comment' => ['type' => Doc\Schema::TYPE_STRING],
'entity' => self::getDropdownTypeSchema(class: Entity::class, full_schema: 'Entity'),
'is_recursive' => ['type' => Doc\Schema::TYPE_BOOLEAN],
'is_active' => [
'type' => Doc\Schema::TYPE_BOOLEAN,
'description' => 'Whether the item is currently active for reservations',
],
],
],
'Reservation' => [
'x-version-introduced' => '2.1.0',
'x-itemtype' => ReservationItem::class,
'type' => Doc\Schema::TYPE_OBJECT,
'properties' => [
'id' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'readOnly' => true,
],
'reservable_item' => [
'type' => Doc\Schema::TYPE_OBJECT,
'x-field' => 'reservationitems_id',
'x-itemtype' => ReservationItem::class,
'x-join' => [
'table' => ReservationItem::getTable(),
'fkey' => 'reservationitems_id',
'field' => 'id',
],
'properties' => [
'id' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'readOnly' => true,
],
'itemtype' => [
'type' => Doc\Schema::TYPE_STRING,
'description' => 'The itemtype of the reservable item',
],
'items_id' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'description' => 'The ID of the reservable item',
],
],
],
'comment' => ['type' => Doc\Schema::TYPE_STRING],
'user' => self::getDropdownTypeSchema(class: User::class, full_schema: 'User'),
'group' => [
'type' => Doc\Schema::TYPE_INTEGER,
'format' => Doc\Schema::FORMAT_INTEGER_INT64,
'description' => 'A random number used to identify reservations that are part of the same series (recurring reservations)',
],
'date_begin' => [
'type' => Doc\Schema::TYPE_STRING,
'format' => Doc\Schema::FORMAT_STRING_DATE_TIME,
'x-field' => 'begin',
],
'date_end' => [
'type' => Doc\Schema::TYPE_STRING,
'format' => Doc\Schema::FORMAT_STRING_DATE_TIME,
'x-field' => 'end',
],
],
],
];
}

/**
* @param bool $types_only If true, only the type names are returned. If false, the type name => localized name pairs are returned.
* @return array<class-string<CommonDBTM>, string>
*/
public static function getToolTypes(bool $types_only = true): array
{
static $types = null;

if ($types === null) {
$types = [
'Reminder' => Reminder::getTypeName(1),
'RSSFeed' => RSSFeed::getTypeName(1),
];
}
return $types_only ? array_keys($types) : $types;
}

#[Route(path: '/', methods: ['GET'], middlewares: [ResultFormatterMiddleware::class])]
#[RouteVersion(introduced: '2.1')]
#[Doc\Route(
description: 'Get all available tool types',
responses: [
new Doc\Response(new Doc\Schema(
type: Doc\Schema::TYPE_ARRAY,
items: new Doc\Schema(
type: Doc\Schema::TYPE_OBJECT,
properties: [
'itemtype' => new Doc\Schema(Doc\Schema::TYPE_STRING),
'name' => new Doc\Schema(Doc\Schema::TYPE_STRING),
'href' => new Doc\Schema(Doc\Schema::TYPE_STRING),
]
)
)),
]
)]
public function index(Request $request): Response
{
$tool_types = self::getToolTypes(false);
$tool_paths = [];
foreach ($tool_types as $tool_type => $tool_name) {
$tool_paths[] = [
'itemtype' => $tool_type,
'name' => $tool_name,
'href' => self::getAPIPathForRouteFunction(self::class, 'search', ['itemtype' => $tool_type]),
];
}
return new JSONResponse($tool_paths);
}

#[Route(path: '/{itemtype}', methods: ['GET'], requirements: [
'itemtype' => [self::class, 'getToolTypes'],
], middlewares: [ResultFormatterMiddleware::class])]
#[RouteVersion(introduced: '2.1')]
#[Doc\SearchRoute(schema_name: '{itemtype}')]
public function search(Request $request): Response
{
$itemtype = $request->getAttribute('itemtype');
return ResourceAccessor::searchBySchema($this->getKnownSchema($itemtype, $this->getAPIVersion($request)), $request->getParameters());
}

#[Route(path: '/{itemtype}/{id}', methods: ['GET'], requirements: [
'itemtype' => [self::class, 'getToolTypes'],
'id' => '\d+',
], middlewares: [ResultFormatterMiddleware::class])]
#[RouteVersion(introduced: '2.1')]
#[Doc\GetRoute(schema_name: '{itemtype}')]
public function getItem(Request $request): Response
{
$itemtype = $request->getAttribute('itemtype');
return ResourceAccessor::getOneBySchema($this->getKnownSchema($itemtype, $this->getAPIVersion($request)), $request->getAttributes(), $request->getParameters());
}

#[Route(path: '/{itemtype}', methods: ['POST'], requirements: [
'itemtype' => [self::class, 'getToolTypes'],
])]
#[RouteVersion(introduced: '2.1')]
#[Doc\CreateRoute(schema_name: '{itemtype}')]
public function createItem(Request $request): Response
{
$itemtype = $request->getAttribute('itemtype');
return ResourceAccessor::createBySchema($this->getKnownSchema($itemtype, $this->getAPIVersion($request)), $request->getParameters() + ['itemtype' => $itemtype], [self::class, 'getItem']);
}

#[Route(path: '/{itemtype}/{id}', methods: ['PATCH'], requirements: [
'itemtype' => [self::class, 'getToolTypes'],
'id' => '\d+',
])]
#[RouteVersion(introduced: '2.1')]
#[Doc\UpdateRoute(schema_name: '{itemtype}')]
public function updateItem(Request $request): Response
{
$itemtype = $request->getAttribute('itemtype');
return ResourceAccessor::updateBySchema($this->getKnownSchema($itemtype, $this->getAPIVersion($request)), $request->getAttributes(), $request->getParameters());
}

#[Route(path: '/{itemtype}/{id}', methods: ['DELETE'], requirements: [
'itemtype' => [self::class, 'getToolTypes'],
'id' => '\d+',
])]
#[RouteVersion(introduced: '2.1')]
#[Doc\DeleteRoute(schema_name: '{itemtype}')]
public function deleteItem(Request $request): Response
{
$itemtype = $request->getAttribute('itemtype');
return ResourceAccessor::deleteBySchema($this->getKnownSchema($itemtype, $this->getAPIVersion($request)), $request->getAttributes(), $request->getParameters());
}
}
26 changes: 26 additions & 0 deletions src/Glpi/Api/HL/OpenAPIGenerator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,32 @@ public static function getComponentSchemas(string $api_version): array
$itemtype = $known_schema['x-itemtype'];
$known_schema['description'] = $itemtype::getTypeName(1);
}

// Add properties that have 'required' flags to a 'required' array on the nearest parent object
// We add the 'required' on individual properties so that it works well with the API version filtering
$fn_hoist_required_flags = static function (&$schema_part) use (&$fn_hoist_required_flags) {
if (is_array($schema_part)) {
if (isset($schema_part['properties']) && is_array($schema_part['properties'])) {
$required_fields = [];
foreach ($schema_part['properties'] as $prop_name => &$prop_value) {
if (is_array($prop_value)) {
if (isset($prop_value['required']) && $prop_value['required'] === true) {
$required_fields[] = $prop_name;
unset($prop_value['required']);
}
// Recurse into the property value
$fn_hoist_required_flags($prop_value);
}
}
unset($prop_value);
if (count($required_fields) > 0) {
$schema_part['required'] = $required_fields;
}
}
}
};
$fn_hoist_required_flags($known_schema);

$schemas[$calculated_name] = $known_schema;
$schemas[$calculated_name]['x-controller'] = $controller::class;
$schemas[$calculated_name]['x-schemaname'] = $schema_name;
Expand Down
Loading
Loading