apirest.md 51.7 KB
Newer Older
Remi Collet's avatar
Remi Collet committed
1
# GLPI REST API:  Documentation
Alexandre Delaunay's avatar
Alexandre Delaunay committed
2

3
## Summary
Alexandre Delaunay's avatar
Alexandre Delaunay committed
4 5 6

* [Glossary](#glossary)
* [Important](#important)
7 8
* [Init session](#init-session)
* [Kill session](#kill-session)
9
* [Lost password](#lost-password)
10 11 12 13 14 15 16
* [Get my profiles](#get-my-profiles)
* [Get active profile](#get-active-profile)
* [Change active profile](#change-active-profile)
* [Get my entities](#get-my-entities)
* [Get active entities](#get-active-entities)
* [Change active entities](#change-active-entities)
* [Get full session](#get-full-session)
Remi Collet's avatar
Remi Collet committed
17
* [Get GLPI config](#get-glpi-config)
18 19 20
* [Get an item](#get-an-item)
* [Get all items](#get-all-items)
* [Get sub items](#get-sub-items)
21
* [Get multiple items](#get-multiple-items)
22 23
* [List searchOptions](#list-searchoptions)
* [Search items](#search-items)
Guillaume Bougard's avatar
Guillaume Bougard committed
24 25 26
* [Add item(s)](#add-items)
* [Update item(s)](#update-items)
* [Delete item(s)](#delete-items)
btry's avatar
btry committed
27
* [Special cases](#special-cases)
Alexandre Delaunay's avatar
Alexandre Delaunay committed
28
* [Errors](#errors)
29
* [Servers configuration](#servers-configuration)
Alexandre Delaunay's avatar
Alexandre Delaunay committed
30

31
## Glossary
Alexandre Delaunay's avatar
Alexandre Delaunay committed
32

Alexandre Delaunay's avatar
Alexandre Delaunay committed
33
Endpoint
34 35
:   Resource available though the API.
    The endpoint is the URL where your API can be accessed by a client application
Alexandre Delaunay's avatar
Alexandre Delaunay committed
36 37 38 39 40

Method
:   HTTP verbs to indicate the desired action to be performed on the identified resource.
    See: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods

Alexandre Delaunay's avatar
Alexandre Delaunay committed
41
itemtype
42
:   A GLPI type, could be an asset, an ITIL or a configuration object, etc.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
43
    This type must be a class who inherits CommonDTBM GLPI class.
44
    See [List itemtypes](https://forge.glpi-project.org/apidoc/class-CommonDBTM.html).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
45 46

searchOption
Alexandre Delaunay's avatar
Alexandre Delaunay committed
47
:   A column identifier (integer) of an itemtype (ex: 1 -> id, 2 -> name, ...).
48
    See [List searchOptions](#list-searchoptions) endpoint.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
49 50

JSON Payload
51
:   content of HTTP Request in JSON format (HTTP body)
Alexandre Delaunay's avatar
Alexandre Delaunay committed
52

Alexandre Delaunay's avatar
Alexandre Delaunay committed
53
Query string
Alexandre Delaunay's avatar
Alexandre Delaunay committed
54 55
:   URL parameters

Alexandre Delaunay's avatar
Alexandre Delaunay committed
56 57 58 59
User token
:   Used in login process instead of login/password couple.
    It represent the user with a string.
    You can find user token in the settings tabs of users.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
60

Alexandre Delaunay's avatar
Alexandre Delaunay committed
61 62 63 64 65
Session token
:   A string describing a valid session in glpi.
    Except initSession endpoint who provide this token, all others require this string to be used.

App(lication) token
66
:   An optional way to filter the access to the API.
67
    On API call, it will try to find an API client matching your IP and the app token (if provided).
68
    You can define an API client with an app token in general configuration for each of your external applications to identify them (each API client have its own history).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
69

70
## Important
Alexandre Delaunay's avatar
Alexandre Delaunay committed
71

72
* You should always provide a Content-Type header in your HTTP calls.
73
   Currently, the API supports:
74
  * application/json
75
  * multipart/form-data (for files upload, see [Add item(s)](#add-item-s) endpoint.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
76 77 78 79 80

* GET requests must have an empty body. You must pass all parameters in URL.
  Failing to do so will trigger an HTTP 400 response.

* By default, sessions used in this API are read-only.
81
  Only some methods have write access to session:
82 83 84
  * [initSession](#init-session)
  * [killSession](#kill-session)
  * [changeActiveEntities](#change-active-entities)
85
  * [changeActiveProfile](#change-active-profile)
Alexandre Delaunay's avatar
Alexandre Delaunay committed
86 87 88 89 90

  You could pass an additional parameter "session_write=true" to bypass this default.
  This read-only mode allow to use this API with parallel calls.
  In write mode, sessions are locked and your client must wait the end of a call before the next one can execute.

Remi Collet's avatar
Remi Collet committed
91
* You can filter API access by enable the following parameters in GLPI General Configuration (API tab):
92 93
  * IPv4 range
  * IPv6 address
94
  * *App-Token* parameter: if not empty, you should pass this parameter in all of your API calls
Alexandre Delaunay's avatar
Alexandre Delaunay committed
95

Alexandre Delaunay's avatar
Alexandre Delaunay committed
96 97
* Session and App tokens could be provided in query string instead of header parameters.

98
## Init session
Alexandre Delaunay's avatar
Alexandre Delaunay committed
99

100
* **URL**: apirest.php/initSession/
101
* **Description**: Request a session token to uses other API endpoints.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
102
* **Method**: GET
103
* **Parameters**: (Headers)
104
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
105 106 107
  * a couple *login* & *password*: 2 parameters to login with user authentication.
     You should pass this 2 parameters in [http basic auth](https://en.wikipedia.org/wiki/Basic_access_authentication).
     It consists in a Base64 string with login and password separated by ":"
Alexandre Delaunay's avatar
Alexandre Delaunay committed
108
     A valid Authorization header is:
109
        * "Authorization: Basic base64({login}:{password})"
Alexandre Delaunay's avatar
Alexandre Delaunay committed
110

111
    > **OR**
Alexandre Delaunay's avatar
Alexandre Delaunay committed
112

113
  * an *user_token* defined in User Preference (See 'Remote access key')
Alexandre Delaunay's avatar
Alexandre Delaunay committed
114
     You should pass this parameter in 'Authorization' HTTP header.
115
     A valid Authorization header is:
116
        * "Authorization: user_token q56hqkniwot8wntb3z1qarka5atf365taaa2uyjrn"
117 118
* **Parameters**: (query string)
  * *get_full_session* (default: false): Get the full session, useful if you want to login and access session data in one request.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
119
* **Returns**:
120
  * 200 (OK) with the *session_token* string.
121 122
  * 400 (Bad Request) with a message indicating an error in input parameter.
  * 401 (UNAUTHORIZED)
Alexandre Delaunay's avatar
Alexandre Delaunay committed
123 124 125 126 127 128 129

Examples usage (CURL):

```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
-H "Authorization: Basic Z2xwaTpnbHBp" \
130
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
131
'http://path/to/glpi/apirest.php/initSession'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
132 133 134

< 200 OK
< {
135
   "session_token": "83af7e620c83a50a18d3eac2f6ed05a3ca0bea62"
Alexandre Delaunay's avatar
Alexandre Delaunay committed
136 137 138 139
}

$ curl -X GET \
-H 'Content-Type: application/json' \
140
-H "Authorization: user_token q56hqkniwot8wntb3z1qarka5atf365taaa2uyjrn" \
141
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
142
'http://path/to/glpi/apirest.php/initSession?get_full_session=true'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
143 144 145

< 200 OK
< {
146
   "session_token": "83af7e620c83a50a18d3eac2f6ed05a3ca0bea62",
147 148 149 150 151 152
   "session": {
      'glpi_plugins': ...,
      'glpicookietest': ...,
      'glpicsrftokens': ...,
      ...
   }
Alexandre Delaunay's avatar
Alexandre Delaunay committed
153 154 155
}
```

156
## Kill session
Alexandre Delaunay's avatar
Alexandre Delaunay committed
157

158
* **URL**: apirest.php/killSession/
Alexandre Delaunay's avatar
Alexandre Delaunay committed
159 160
* **Description**: Destroy a session identified by a session token.
* **Method**: GET
161 162
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
163
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
164 165 166
* **Returns**:
  * 200 (OK).
  * 400 (Bad Request) with a message indicating an error in input parameter.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
167 168 169 170 171 172

Example usage (CURL):

```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
173 174
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
175
'http://path/to/glpi/apirest.php/killSession'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
176 177 178 179

< 200 OK
```

180 181 182 183 184 185 186 187 188 189 190
## Lost password

This endpoint allows to request password recovery and password reset. This endpoint works under the following 
conditions:
* GLPI has notifications enabled
* the email address of the user belongs to a user account.

Reset password request:

* **URL**: apirest.php/lostPassword/
* **Description**: Sends a notification to the user to reset his password
191
* **Method**: PUT or PATCH
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
* **Parameters**: (JSON Payload)
  * *email*: email address of the user to recover. Mandatory.
* **Returns**:
  * 200 (OK).
  * 400 (Bad Request) with a message indicating an error in input parameter.

```bash
$ curl -X PUT \
-H 'Content-Type: application/json' \
-d '{"email": "user@domain.com"}' \
'http://path/to/glpi/apirest.php/lostPassword'

< 200 OK
```

Password reset :

* **URL**: apirest.php/lostPassword/
* **Description**: Sends a notification to the user to reset his password
211
* **Method**: PUT or PATCH
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
* **Parameters**: (JSON Payload)
  * *email*: email address of the user to recover. Mandatory.
  * *password_forget_token*: reset token
  * *password*: the new password for the user
* **Returns**:
  * 200 (OK).
  * 400 (Bad Request) with a message indicating an error in input parameter.

```bash
$ curl -X PUT \
-H 'Content-Type: application/json' \
-d '{"email": "user@domain.com", \
     "password_forget_token": "b0a4cfe81448299ebed57442f4f21929c80ebee5" \
     "password": "NewPassword" \
    }' \
'http://path/to/glpi/apirest.php/lostPassword'

< 200 OK
```

232
## Get my profiles
Alexandre Delaunay's avatar
Alexandre Delaunay committed
233

234 235
* **URL**: [apirest.php/getMyProfiles/](getMyProfiles/?debug)
* **Description**: Return all the profiles associated to logged user.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
236
* **Method**: GET
237 238
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
239
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
240 241 242
* **Returns**:
  * 200 (OK) with an array of all profiles.
  * 400 (Bad Request) with a message indicating an error in input parameter.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
243 244 245 246

Example usage (CURL):

```bash
247
$ curl -X GET \
Alexandre Delaunay's avatar
Alexandre Delaunay committed
248
-H 'Content-Type: application/json' \
249 250
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
251
'http://path/to/glpi/apirest.php/getMyProfiles'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
252 253

< 200 OK
254 255 256 257 258
< {
   'myprofiles': [
      {
         'id': 1
         'name': "Super-admin",
259
         'entities': [
260
            ...
261
         ],
262 263
         ...
      },
264 265
      ....
   ]
Alexandre Delaunay's avatar
Alexandre Delaunay committed
266 267
```

268
## Get active profile
Alexandre Delaunay's avatar
Alexandre Delaunay committed
269

270
* **URL**: [apirest.php/getActiveProfile/](getActiveProfile/?debug)
271
* **Description**: Return the current active profile.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
272
* **Method**: GET
273 274
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
275
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
276 277 278
* **Returns**:
  * 200 (OK) with an array representing current profile.
  * 400 (Bad Request) with a message indicating an error in input parameter.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
279 280 281 282

Example usage (CURL):

```bash
283
$ curl -X GET \
Alexandre Delaunay's avatar
Alexandre Delaunay committed
284
-H 'Content-Type: application/json' \
285 286
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
287
'http://path/to/glpi/apirest.php/getActiveProfile'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
288 289 290

< 200 OK
< {
291
      'name': "Super-admin",
292
      'entities': [
293
         ...
294
      ]
295
   }
Alexandre Delaunay's avatar
Alexandre Delaunay committed
296 297
```

298
## Change active profile
Alexandre Delaunay's avatar
Alexandre Delaunay committed
299

300
* **URL**: [apirest.php/changeActiveProfile/](changeActiveProfile/?profiles_id=4&debug)
301
* **Description**: Change active profile to the profiles_id one. See [getMyProfiles](#get-my-profiles) endpoint for possible profiles.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
302
* **Method**: POST
303 304
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
305
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
306 307 308 309 310
* **Parameters**: (JSON Payload)
  * *profiles_id*: (default 'all') ID of the new active profile. Mandatory.
* **Returns**:
  * 200 (OK).
  * 400 (Bad Request) with a message indicating an error in input parameter.
311
  * 404 (Not found) with a message indicating an error ig the profile does not exists or usable.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
312 313 314 315 316 317

Example usage (CURL):

```bash
$ curl -X POST \
-H 'Content-Type: application/json' \
318 319
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
Alexandre Delaunay's avatar
Alexandre Delaunay committed
320
-d '{"profiles_id": 4}' \
321
'http://path/to/glpi/apirest.php/changeActiveProfile'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
322 323 324 325

< 200 OK
```

326
## Get my entities
Alexandre Delaunay's avatar
Alexandre Delaunay committed
327

328
* **URL**: [apirest.php/getMyEntities/](getMyEntities/?debug)
329
* **Description**: Return all the possible entities of the current logged user (and for current active profile).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
330
* **Method**: GET
331 332
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
333
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
334 335
* **Parameters**: (query string)
  * *is_recursive* (default: false): Also display sub entities of the active entity. Optionnal
336 337 338
* **Returns**:
  * 200 (OK) with an array of all entities (with id and name).
  * 400 (Bad Request) with a message indicating an error in input parameter.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
339 340 341 342

Example usage (CURL):

```bash
343
$ curl -X GET \
Alexandre Delaunay's avatar
Alexandre Delaunay committed
344
-H 'Content-Type: application/json' \
345 346
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
347
'http://path/to/glpi/apirest.php/getMyEntities'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
348 349

< 200 OK
350 351 352 353 354 355
< {
   'myentities': [
     {
       'id':   71
       'name': "my_entity"
     },
Alexandre Delaunay's avatar
Alexandre Delaunay committed
356
   ....
357 358
   ]
  }
Alexandre Delaunay's avatar
Alexandre Delaunay committed
359 360
```

361
## Get active entities
Alexandre Delaunay's avatar
Alexandre Delaunay committed
362

363
* **URL**: [apirest.php/getActiveEntities/](getActiveEntities/?debug)
364
* **Description**: Return active entities of current logged user.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
365
* **Method**: GET
366 367
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
368
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
369 370 371 372 373 374
* **Returns**:
  * 200 (OK) with an array with 3 keys:
    * *active_entity*: current set entity.
    * *active_entity_recursive*: boolean, if we see sons of this entity.
    * *active_entities*: array all active entities (active_entity and its sons).
  * 400 (Bad Request) with a message indicating an error in input parameter.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
375 376 377 378

Example usage (CURL):

```bash
379
$ curl -X GET \
Alexandre Delaunay's avatar
Alexandre Delaunay committed
380
-H 'Content-Type: application/json' \
381 382
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
Johan Cwiklinski's avatar
Johan Cwiklinski committed
383
'http://path/to/glpi/apirest.php/getActiveEntities'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
384 385 386

< 200 OK
< {
387 388 389
   'active_entity': {
      'id': 1,
      'active_entity_recursive': true,
390 391 392 393
      'active_entities': [
        {"id":1},
        {"id":71},...
      ]
394
   }
395 396 397
}
```

398
## Change active entities
399 400

* **URL**: [apirest.php/changeActiveEntities/](changeActiveEntities/?entities_id=1&is_recursive=0&debug)
401
* **Description**: Change active entity to the entities_id one. See [getMyEntities](#get-my-entities) endpoint for possible entities.
402
* **Method**: POST
403 404
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
405
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
406 407 408 409 410 411
* **Parameters**: (JSON Payload)
  * *entities_id*: (default 'all') ID of the new active entity ("all" => load all possible entities). Optional.
  * *is_recursive*: (default false) Also display sub entities of the active entity.  Optional.
* **Returns**:
  * 200 (OK).
  * 400 (Bad Request) with a message indicating an error in input parameter.
412 413 414 415 416 417

Example usage (CURL):

```bash
$ curl -X POST \
-H 'Content-Type: application/json' \
418 419
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
420 421 422 423
-d '{"entities_id": 1, "is_recursive": true}' \
'http://path/to/glpi/apirest.php/changeActiveEntities'

< 200 OK
Alexandre Delaunay's avatar
Alexandre Delaunay committed
424 425
```

426
## Get full session
Alexandre Delaunay's avatar
Alexandre Delaunay committed
427

428
* **URL**: [apirest.php/getFullSession/](getFullSession/?debug)
429
* **Description**: Return the current php $_SESSION.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
430
* **Method**: GET
431 432
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
433
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
434 435 436
* **Returns**:
  * 200 (OK) with an array representing the php session.
  * 400 (Bad Request) with a message indicating an error in input parameter.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
437 438 439 440

Example usage (CURL):

```bash
441
$ curl -X GET \
Alexandre Delaunay's avatar
Alexandre Delaunay committed
442
-H 'Content-Type: application/json' \
443 444
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
445
'http://path/to/glpi/apirest.php/getFullSession'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
446 447 448

< 200 OK
< {
449 450 451 452 453 454 455 456 457
      'session': {
         'glpi_plugins': ...,
         'glpicookietest': ...,
         'glpicsrftokens': ...,
         ...
      }
   }
```

Remi Collet's avatar
Remi Collet committed
458
## Get GLPI config
459 460 461 462 463 464

* **URL**: [apirest.php/getGlpiConfig/](getGlpiConfig/?debug)
* **Description**: Return the current $CFG_GLPI.
* **Method**: GET
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
465
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
466 467 468 469 470 471 472
* **Returns**:
  * 200 (OK) with an array representing the php global variable $CFG_GLPI.
  * 400 (Bad Request) with a message indicating an error in input parameter.

Example usage (CURL):

```bash
btry's avatar
btry committed
473
$ curl -X GET \
474 475 476 477 478 479 480 481 482 483 484 485 486
-H 'Content-Type: application/json' \
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
'http://path/to/glpi/apirest.php/getGlpiConfig'

< 200 OK
< {
      'cfg_glpi': {
         'languages': ...,
         'glpitables': ...,
         'unicity_types':...,
         ...
      }
Alexandre Delaunay's avatar
Alexandre Delaunay committed
487 488 489
   }
```

490
## Get an item
Alexandre Delaunay's avatar
Alexandre Delaunay committed
491

492
* **URL**: [apirest.php/:itemtype/:id](User/2?debug)
493
* **Description**: Return the instance fields of itemtype identified by id.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
494
* **Method**: GET
495 496
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
497
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
498 499 500 501 502
* **Parameters**: (query string)
  * *id*: unique identifier of the itemtype. Mandatory.
  * *expand_dropdowns* (default: false): show dropdown name instead of id. Optional.
  * *get_hateoas* (default: true): Show relations of the item in a links attribute. Optional.
  * *get_sha1* (default: false): Get a sha1 signature instead of the full answer. Optional.
503
  * *with_devices*: Only for [Computer, NetworkEquipment, Peripheral, Phone, Printer], retrieve the associated components. Optional.
504 505 506 507 508 509 510
  * *with_disks*: Only for Computer, retrieve the associated file-systems. Optional.
  * *with_softwares*: Only for Computer, retrieve the associated software's installations. Optional.
  * *with_connections*: Only for Computer, retrieve the associated direct connections (like peripherals and printers) .Optional.
  * *with_networkports*: Retrieve all network's connections and advanced network's informations. Optional.
  * *with_infocoms*: Retrieve financial and administrative informations. Optional.
  * *with_contracts*: Retrieve associated contracts. Optional.
  * *with_documents*: Retrieve associated external documents. Optional.
511 512 513
  * *with_tickets*: Retrieve associated ITIL tickets. Optional.
  * *with_problems*: Retrieve associated ITIL problems. Optional.
  * *with_changes*: Retrieve associated ITIL changes. Optional.
514 515
  * *with_notes*: Retrieve Notes. Optional.
  * *with_logs*: Retrieve historical. Optional.
516
  * *add_keys_names*: Retrieve friendly names. Array containing fkey(s) and/or "id". Optional.
517 518 519 520
* **Returns**:
  * 200 (OK) with item data (Last-Modified header should contain the date of last modification of the item).
  * 401 (UNAUTHORIZED).
  * 404 (NOT FOUND).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
521 522 523 524 525 526

Example usage (CURL):

```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
527 528
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
529
'http://path/to/glpi/apirest.php/Computer/71?expand_dropdowns=true'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
530 531 532

< 200 OK
< {
Alexandre Delaunay's avatar
Alexandre Delaunay committed
533
    "id": 71,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
534 535 536 537 538 539 540 541 542 543 544 545 546 547 548
    "entities_id": "Root Entity",
    "name": "adelaunay-ThinkPad-Edge-E320",
    "serial": "12345",
    "otherserial": "test2",
    "contact": "adelaunay",
    "contact_num": null,
    "users_id_tech": " ",
    "groups_id_tech": " ",
    "comment": "test222222qsdqsd",
    "date_mod": "2015-09-25 09:33:41",
    "autoupdatesystems_id": " ",
    "locations_id": "00:0e:08:3b:7d:04",
    "networks_id": " ",
    "computermodels_id": "1298A8G",
    "computertypes_id": "Notebook",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
549
    "is_template": 0,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
550 551
    "template_name": null,
    "manufacturers_id": "LENOVO",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
552 553
    "is_deleted": 0,
    "is_dynamic": 1,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587
    "users_id": "adelaunay",
    "groups_id": " ",
    "states_id": "Production",
    "ticket_tco": "0.0000",
    "uuid": "",
    "date_creation": null,
    "links": [{
       "rel": "Entity",
       "href": "http://path/to/glpi/api/Entity/0"
    }, {
       "rel": "Location",
       "href": "http://path/to/glpi/api/Location/3"
    }, {
       "rel": "Domain",
       "href": "http://path/to/glpi/api/Domain/18"
    }, {
       "rel": "ComputerModel",
       "href": "http://path/to/glpi/api/ComputerModel/11"
    }, {
       "rel": "ComputerType",
       "href": "http://path/to/glpi/api/ComputerType/3"
    }, {
       "rel": "Manufacturer",
       "href": "http://path/to/glpi/api/Manufacturer/260"
    }, {
       "rel": "User",
       "href": "http://path/to/glpi/api/User/27"
    }, {
       "rel": "State",
       "href": "http://path/to/glpi/api/State/1"
    }]
}
```

Thierry Bugier Pineau's avatar
Thierry Bugier Pineau committed
588
Note: To download a document see [Download a document file](#download-a-document-file).
btry's avatar
btry committed
589

590
## Get all items
Alexandre Delaunay's avatar
Alexandre Delaunay committed
591

592
* **URL**: [apirest.php/:itemtype/](Computer/?debug)
593
* **Description**: Return a collection of rows of the itemtype.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
594
* **Method**: GET
595 596
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
597
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
598 599 600 601 602
* **Parameters**: (query string)
  * *expand_dropdowns* (default: false): show dropdown name instead of id. Optional.
  * *get_hateoas* (default: true): Show relation of item in a links attribute. Optional.
  * *only_id* (default: false): keep only id keys in returned data. Optional.
  * *range* (default: 0-50):  a string with a couple of number for start and end of pagination separated by a '-'. Ex: 150-200. Optional.
603
  * *sort* (default 1): name of the field to sort by. Optional.
604
  * *order* (default ASC): ASC - Ascending sort / DESC Descending sort. Optional.
605
  * *searchText* (default NULL): array of filters to pass on the query (with key = field and value the text to search)
606
  * *is_deleted* (default: false): Return deleted element. Optional.
607
  * *add_keys_names*: Retrieve friendly names. Array containing fkey(s) and/or "id". Optional.
608 609 610 611
* **Returns**:
  * 200 (OK) with items data.
  * 206 (PARTIAL CONTENT) with items data defined by range.
  * 401 (UNAUTHORIZED).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
612 613 614 615 616 617 618 619 620 621

   and theses headers:
      * *Content-Range* offset – limit / count
      * *Accept-Range* itemtype max

Example usage (CURL):

```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
622 623
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
624
'http://path/to/glpi/apirest.php/Computer/?expand_dropdowns=true'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
625

626
< 206 OK
Alexandre Delaunay's avatar
Alexandre Delaunay committed
627 628 629 630
< Content-Range: 0-50/200
< Accept-Range: 990
< [
   {
Alexandre Delaunay's avatar
Alexandre Delaunay committed
631
      "id": 34,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
632 633 634 635 636 637 638 639 640 641 642 643 644 645 646
      "entities_id": "Root Entity",
      "name": "glpi",
      "serial": "VMware-42 01 f4 65 27 59 a9 fb-11 bc cd b8 64 68 1f 4b",
      "otherserial": null,
      "contact": "teclib",
      "contact_num": null,
      "users_id_tech": "&nbsp;",
      "groups_id_tech": "&nbsp;",
      "comment": "x86_64/00-09-15 08:03:28",
      "date_mod": "2011-12-16 17:52:55",
      "autoupdatesystems_id": "FusionInventory",
      "locations_id": "&nbsp;",
      "networks_id": "&nbsp;",
      "computermodels_id": "VMware Virtual Platform",
      "computertypes_id": "Other",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
647
      "is_template": 0,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
648 649
      "template_name": null,
      "manufacturers_id": "VMware, Inc.",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
650 651
      "is_deleted": 0,
      "is_dynamic": 1,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680
      "users_id": "&nbsp;",
      "groups_id": "&nbsp;",
      "states_id": "Production",
      "ticket_tco": "0.0000",
      "uuid": "4201F465-2759-A9FB-11BC-CDB864681F4B",
      "links": [{
         "rel": "Entity",
         "href": "http://path/to/glpi/api/Entity/0"
      }, {
         "rel": "AutoUpdateSystem",
         "href": "http://path/to/glpi/api/AutoUpdateSystem/1"
      }, {
         "rel": "Domain",
         "href": "http://path/to/glpi/api/Domain/12"
      }, {
         "rel": "ComputerModel",
         "href": "http://path/to/glpi/api/ComputerModel/1"
      }, {
         "rel": "ComputerType",
         "href": "http://path/to/glpi/api/ComputerType/2"
      }, {
         "rel": "Manufacturer",
         "href": "http://path/to/glpi/api/Manufacturer/1"
      }, {
         "rel": "State",
         "href": "http://path/to/glpi/api/State/1"
      }]
   },
   {
Alexandre Delaunay's avatar
Alexandre Delaunay committed
681
      "id": 35,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
682 683 684 685 686 687 688 689 690 691 692 693 694 695 696
      "entities_id": "Root Entity",
      "name": "mavm1",
      "serial": "VMware-42 20 d3 04 ac 49 ed c8-ea 15 50 49 e1 40 0f 6c",
      "otherserial": null,
      "contact": "teclib",
      "contact_num": null,
      "users_id_tech": "&nbsp;",
      "groups_id_tech": "&nbsp;",
      "comment": "x86_64/01-01-04 19:50:40",
      "date_mod": "2012-05-24 06:43:35",
      ...
   }
]
```

697
## Get sub items
Alexandre Delaunay's avatar
Alexandre Delaunay committed
698

699
* **URL**: [apirest.php/:itemtype/:id/:sub_itemtype](User/2/Log?debug)
700
* **Description**: Return a collection of rows of the sub_itemtype for the identified item.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
701
* **Method**: GET
702 703
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
704
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
705 706 707 708 709 710 711 712
* **Parameters**: (query string)
  * id: unique identifier of the parent itemtype. Mandatory.
  * *expand_dropdowns* (default: false): show dropdown name instead of id. Optional.
  * *get_hateoas* (default: true): Show item's relations in a links attribute. Optional.
  * *only_id* (default: false): keep only id keys in returned data. Optional.
  * *range* (default: 0-50): a string with a couple of number for start and end of pagination separated by a '-' char. Ex: 150-200. Optional.
  * *sort* (default 1): id of the "searchoption" to sort by. Optional.
  * *order* (default ASC): ASC - Ascending sort / DESC Descending sort. Optional.
713
  * *add_keys_names*: Retrieve friendly names. Array containing fkey(s) and/or "id". Optional.
714 715 716
* **Returns**:
  * 200 (OK) with the items data.
  * 401 (UNAUTHORIZED).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
717 718 719 720 721 722 723 724 725 726

   and theses headers:
      * *Content-Range* offset – limit / count
      * *Accept-Range* itemtype max

Example usage (CURL):

```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
727 728
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
729
'http://path/to/glpi/apirest.php/User/2/Log'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
730 731 732 733 734 735

< 200 OK
< Content-Range: 0-50/200
< Accept-Range: 990
< [
   {
Alexandre Delaunay's avatar
Alexandre Delaunay committed
736
      "id": 22117,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
737
      "itemtype": "User",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
738
      "items_id": 2,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
739
      "itemtype_link": "Profile",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
740
      "linked_action": 17,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
741 742
      "user_name": "glpi (27)",
      "date_mod": "2015-10-13 10:00:59",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
743
      "id_search_option": 0,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
744 745 746
      "old_value": "",
      "new_value": "super-admin (4)"
   }, {
Alexandre Delaunay's avatar
Alexandre Delaunay committed
747
      "id": 22118,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
748
      "itemtype": "User",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
749
      "items_id": 2,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
750
      "itemtype_link": "",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
751
      "linked_action": 0,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
752 753
      "user_name": "glpi (2)",
      "date_mod": "2015-10-13 10:01:22",
Alexandre Delaunay's avatar
Alexandre Delaunay committed
754
      "id_search_option": 80,
Alexandre Delaunay's avatar
Alexandre Delaunay committed
755 756 757 758 759 760 761 762
      "old_value": "Root entity (0)",
      "new_value": "Root entity > my entity (1)"
   }, {
      ...
   }
]
```

763 764 765
## Get multiple items

* **URL**: apirest.php/getMultipleItems
766
* **Description**: Virtually call [Get an item](#get-an-item) for each line in input. So, you can have a ticket, a user in the same query.
767
* **Method**: GET
768 769
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
770
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
771 772
* **Parameters**: (query string)
  * *items*: items to retrieve. Mandatory.
773
              Each line of this array should contains two keys:
774 775 776 777 778
              * itemtype
              * items_id
  * *expand_dropdowns* (default: false): show dropdown name instead of id. Optional.
  * *get_hateoas* (default: true): Show relations of the item in a links attribute. Optional.
  * *get_sha1* (default: false): Get a sha1 signature instead of the full answer. Optional.
779
  * *with_devices*: Only for [Computer, NetworkEquipment, Peripheral, Phone, Printer], retrieve the associated components. Optional.
780 781 782 783 784 785 786
  * *with_disks*: Only for Computer, retrieve the associated file-systems. Optional.
  * *with_softwares*: Only for Computer, retrieve the associated software's installations. Optional.
  * *with_connections*: Only for Computer, retrieve the associated direct connections (like peripherals and printers) .Optional.
  * *with_networkports*: Retrieve all network's connections and advanced network's informations. Optional.
  * *with_infocoms*: Retrieve financial and administrative informations. Optional.
  * *with_contracts*: Retrieve associated contracts. Optional.
  * *with_documents*: Retrieve associated external documents. Optional.
787 788 789
  * *with_tickets*: Retrieve associated ITIL tickets. Optional.
  * *with_problems*: Retrieve associated ITIL problems. Optional.
  * *with_changes*: Retrieve associated ITIL changes. Optional.
790 791
  * *with_notes*: Retrieve Notes. Optional.
  * *with_logs*: Retrieve historical. Optional.
792
  * *add_keys_names*: Retrieve friendly names. Array containing fkey(s) and/or "id". Optional.
793 794 795 796
* **Returns**:
  * 200 (OK) with item data (Last-Modified header should contain the date of last modification of the item).
  * 401 (UNAUTHORIZED).
  * 404 (NOT FOUND).
797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821

Example usage (CURL):

```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
-d '{"items": [{"itemtype": "User", "items_id": 2}, {"itemtype": "Entity", "items_id": 0}]}' \
'http://path/to/glpi/apirest.php/getMultipleItems?items\[0\]\[itemtype\]\=User&items\[0\]\[items_id\]\=2&items\[1\]\[itemtype\]\=Entity&items\[1\]\[items_id\]\=0'

< 200 OK
< Content-Range: 0-50/200
< Accept-Range: 990
< [{
   "id": 2,
   "name": "glpi",
   ...
}, {
   "id": 0,
   "name": "Root Entity",
   ...
}]
```

822
## List searchOptions
Alexandre Delaunay's avatar
Alexandre Delaunay committed
823

824
* **URL**: [apirest.php/listSearchOptions/:itemtype](listSearchOptions/Computer?debug)
825
* **Description**: List the searchoptions of provided itemtype. To use with [Search items](#search_items).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
826
* **Method**: GET
827 828
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
829
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
830 831 832 833 834
* **Parameters**: (query string)
  * *raw*: return searchoption uncleaned (as provided by core)
* **Returns**:
  * 200 (OK) with all searchoptions of specified itemtype (format: searchoption_id: {option_content}).
  * 401 (UNAUTHORIZED).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
835 836 837 838 839 840

Example usage (CURL):

```bash
$ curl -X GET \
-H 'Content-Type: application/json' \
841 842
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
843
'http://path/to/glpi/apirest.php/listSearchOptions/Computer'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875
< 200 OK
< {
    "common": "Characteristics",

    1: {
      'name': 'Name'
      'table': 'glpi_computers'
      'field': 'name'
      'linkfield': 'name'
      'datatype': 'itemlink'
      'uid': 'Computer.name'
   },
   2: {
      'name': 'ID'
      'table': 'glpi_computers'
      'field': 'id'
      'linkfield': 'id'
      'datatype': 'number'
      'uid': 'Computer.id'
   },
   3: {
      'name': 'Location'
      'table': 'glpi_locations'
      'field': 'completename'
      'linkfield': 'locations_id'
      'datatype': 'dropdown'
      'uid': 'Computer.Location.completename'
   },
   ...
}
```

876
## Search items
Alexandre Delaunay's avatar
Alexandre Delaunay committed
877

878
* **URL**: [apirest.php/search/:itemtype/](search/Computer/?debug)
Remi Collet's avatar
Remi Collet committed
879
* **Description**: Expose the GLPI searchEngine and combine criteria to retrieve a list of elements of specified itemtype.
880
  > Note: you can use 'AllAssets' itemtype to retrieve a combination of all asset's types.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
881
* **Method**: GET
882 883
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
884
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
885 886
* **Parameters**: (query string)
  * *criteria*: array of criterion objects to filter search. Optional.
887 888 889 890 891 892 893 894 895 896 897 898 899 900 901
    You can optionally precise `meta=true` to pass a searchoption of another itemtype (meta-criteria).
    Each criterion object must provide at least:
      * *link*: (optional for 1st element) logical operator in [AND, OR, AND NOT, AND NOT].

      And you can pass a direct searchoption usage :

      * *field*: id of the searchoption.
      * *meta*: boolean, is this criterion a meta one ?
      * *itemtype*: for meta=true criterion, precise the itemtype to use.
      * *searchtype*: type of search in [contains¹, equals², notequals², lessthan, morethan, under, notunder].
      * *value*: the value to search.

      Or a list of sub-nodes with the key:

      * *criteria*: nested criteria inside this criteria.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
902 903 904

      Ex:

Cédric Anne's avatar
Cédric Anne committed
905
      ```json
906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942
      ...
      "criteria":
         [
            {
               "field":      1,
               "searchtype": 'contains',
               "value":      ''
            }, {
               "link":       'AND',
               "field":      31,
               "searchtype": 'equals',
               "value":      1
            }, {
               "link":       'AND',
               "meta":       true,
               "itemtype":   'User',
               "field":      1,
               "searchtype": 'equals',
               "value":      1
            }, {
               "link":       'AND',
               "criteria" : [
                  {
                     "field":      34,
                     "searchtype": 'equals',
                     "value":      1
                  }, {
                     "link":       'OR',
                     "field":      35,
                     "searchtype": 'equals',
                     "value":      1
                  }
               ]
            }
         ]
      ...
      ```
Alexandre Delaunay's avatar
Alexandre Delaunay committed
943

944
  * *metacriteria* (optional): array of meta-criterion objects to filter search. Optional.
945 946 947
                                 A meta search is a link with another itemtype (ex: Computer with softwares).  
      **Deprecated: Now criteria support meta flag, you should use it instead direct metacriteria option.**

Alexandre Delaunay's avatar
Alexandre Delaunay committed
948
      Each meta-criterion object must provide:
949 950 951
        * *link*: logical operator in [AND, OR, AND NOT, AND NOT]. Mandatory.
        * *itemtype*: second itemtype to link.
        * *field*: id of the searchoption.
952
        * *searchtype*: type of search in [contains¹, equals², notequals², lessthan, morethan, under, notunder].
953
        * *value*: the value to search.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
954 955 956

      Ex:

Cédric Anne's avatar
Cédric Anne committed
957
      ```json
958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976
      ...
      "metacriteria":
         [
            {
               "link":       'AND',
               "itemtype":   'Monitor',
               "field":      2,
               "searchtype": 'contains',
               "value":      ''
            }, {
               "link":       'AND',
               "itemtype":   'Monitor',
               "field":      3,
               "searchtype": 'contains',
               "value":      ''
             }
         ]
      ...
      ```
Alexandre Delaunay's avatar
Alexandre Delaunay committed
977

978 979 980
  * *sort* (default 1): id of the searchoption to sort by. Optional.
  * *order* (default ASC): ASC - Ascending sort / DESC Descending sort. Optional.
  * *range* (default 0-50): a string with a couple of number for start and end of pagination separated by a '-'. Ex: 150-200.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
981
                             Optional.
982
  * *forcedisplay*: array of columns to display (default empty = use display preferences and searched criteria).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
983 984
                     Some columns will be always presents (1: id, 2: name, 80: Entity).
                     Optional.
985
  * *rawdata* (default false): a boolean for displaying raws data of the Search engine of GLPI (like SQL request, full searchoptions, etc)
986
  * *withindexes* (default false): a boolean to retrieve rows indexed by items id.
987
   By default this option is set to false, because order of JSON objects (which are identified by index) cannot be garrantued  (from <http://json.org/> : An object is an unordered set of name/value pairs).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
988
   So, we provide arrays to guarantying sorted rows.
989 990
  * *uid_cols* (default false): a boolean to identify cols by the 'uniqid' of the searchoptions instead of a numeric value (see [List searchOptions](#list-searchoptions) and 'uid' field)
  * *giveItems* (default false): a boolean to retrieve the data with the html parsed from core, new data are provided in data_html key.
991 992 993 994

  * ¹ - *contains* will use a wildcard search per default. You can restrict at the beginning using the *^* character, and/or at the end using the *$* character.
  * ² - *equals* and *notequals* are designed to be used with dropdowns. Do not expect those operators to search for a strictly equal value (see ¹ above).

995 996
* **Returns**:
  * 200 (OK) with all rows data with this format:
Alexandre Delaunay's avatar
Alexandre Delaunay committed
997

Cédric Anne's avatar
Cédric Anne committed
998
     ```json
999 1000 1001
        {
            "totalcount": ":numberofresults_without_pagination",
            "range": ":start-:end",
1002 1003
            "data": [
                {
1004 1005 1006
                    ":searchoptions_id": "value",
                    ...
                },
1007
                {
1008
                 ...
1009 1010 1011
                }
            ],
            "rawdata": {
1012
              ...
1013
            }
1014 1015
        }
     ```
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1016

1017 1018
  * 206 (PARTIAL CONTENT) with rows data (pagination doesn't permit to display all rows).
  * 401 (UNAUTHORIZED).
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1019

1020
      and theses headers:
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1021 1022 1023 1024 1025 1026 1027 1028
      * *Content-Range* offset – limit / count
      * *Accept-Range* itemtype max

Example usage (CURL):

```bash
curl -g -X GET \
-H 'Content-Type: application/json' \
1029 1030
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
1031 1032
'http://path/to/glpi/apirest.php/search/Monitor?\
criteria\[0\]\[link\]\=AND\
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1033 1034 1035 1036 1037 1038 1039 1040 1041
\&criteria\[0\]\[itemtype\]\=Monitor\
\&criteria\[0\]\[field\]\=23\
\&criteria\[0\]\[searchtype\]\=contains\
\&criteria\[0\]\[value\]\=GSM\
\&criteria\[1\]\[link\]\=AND\
\&criteria\[1\]\[itemtype\]\=Monitor\
\&criteria\[1\]\[field\]\=1\
\&criteria\[1\]\[searchtype\]\=contains\
\&criteria\[1\]\[value\]\=W2\
1042
\&range\=0-2\&&forcedisplay\[0\]\=1'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1043 1044 1045 1046 1047 1048 1049

< 200 OK
< Content-Range: 0-2/2
< Accept-Range: 990
< {"totalcount":2,"count":2,"data":{"11":{"1":"W2242","80":"Root Entity","23":"GSM"},"7":{"1":"W2252","80":"Root Entity","23":"GSM"}}}%
```

1050
## Add item(s)
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1051

1052
* **URL**: apirest.php/:itemtype/
Remi Collet's avatar
Remi Collet committed
1053
* **Description**: Add an object (or multiple objects) into GLPI.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1054
* **Method**: POST
1055 1056
* **Parameters**: (Headers)
  * *Session-Token*: session var provided by [initSession](#init-session) endpoint. Mandatory.
1057
  * *App-Token*: authorization string provided by the GLPI API configuration. Optional.
1058 1059
* **Parameters**: (JSON Payload)
  * *input*: an object with fields of itemtype to be inserted.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1060 1061 1062 1063 1064
              You can add several items in one action by passing an array of objects.
              Mandatory.

   **Important:**
      In case of 'multipart/data' content_type (aka file upload), you should insert your parameters into
1065
      a 'uploadManifest' parameter.
1066
      Theses serialized data should be a JSON string.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1067

1068 1069 1070 1071 1072 1073 1074 1075
* **Returns**:
  * 201 (OK) with id of added items.
  * 207 (Multi-Status) with id of added items and errors.
  * 400 (Bad Request) with a message indicating an error in input parameter.
  * 401 (UNAUTHORIZED).
  * And additional header can be provided on creation success:
    * Location when adding a single item.
    * Link on bulk addition.
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1076 1077 1078 1079 1080 1081

Examples usage (CURL):

```bash
$ curl -X POST \
-H 'Content-Type: application/json' \
1082 1083
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1084
-d '{"input": {"name": "My single computer", "serial": "12345"}}' \
1085
'http://path/to/glpi/apirest.php/Computer/'
Alexandre Delaunay's avatar
Alexandre Delaunay committed
1086 1087 1088 1089 1090 1091 1092 1093

< 201 OK
< Location: http://path/to/glpi/api/Computer/15
< {"id": 15}


$ curl -X POST \
-H 'Content-Type: application/json' \