REST API - View a list of groups

Last modified on 2023/04/17 15:16

Contents

Notes
List of parameters / fields
- Mandatory parameters
- Optional parameters
Fields that could be used in optional parameters
HTTP status codes for the method
Example
- Result for 3 groups (status code 200)
REST API Conventions

Minimum version Service Manager : 2023.2 - Build 2023.2.111.0

GET /groups

This method allows a list of groups to be obtained.

To obtain detailed information for a specified group: GET /groups/{group_id}. See the method

Notes

Open url.png See Service Manager REST API Conventions

If successful, a HTTP status code 200 is returned.
- By default, if the optional parameter fields is not used, only an extract of the most useful fields selected by EasyVista is displayed for each record provided.
- A URL link (HREF) to each resource is provided so that the complete list of fields for a record can be obtained.

List of parameters / fields

Mandatory parameters

None

Optional parameters

You can use the parameters detailed below in the HTTP request string.

Minimum version	Parameter	Type	Description / Example
	max_rows	integer	Maximum number of records to display. Default value: 100 example /groups?max_rows=5
	sort	string	Sort in ascending or descending order. Syntax: field1[+asc\|+desc],field2[+asc\|+desc],fieldn[+asc\|+desc] example /groups?sort=group_en+asc
	fields	string	Select fields to display. example /groups?fields=email
	search	string	Search/filter the specified fields. See Description of the options. example /groups?search=email:group_via_rest@easyvista.com
Oxygen 2.1.2 - Build 2018.1.183.0	search (logical OR operator)	string	Search/filter to several values from a same field Syntax: search=field:value1,field:value2 example /groups?search=email:group@easyvista.com, email:group2@easyvista.com ==> all the groups in which the email field is equal to group@easyvista.com or group2@easyvista.com
Oxygen 1.7 - Build 2018.1.131.0	~ (equivalent to like)	string	Include the results which begin with or contain a given character string. Syntax: ~ following by the string to include enclosed in quotation marks. You should use the wildcard character . < string > = include what begins with < string >. < string > = include what contains < string >. example /groups?search=email~"group" ==> all the groups in which the email* field begins with group /groups?search=email~"oup"" ==> all the groups in which the email field contains oup
Oxygen 1.7 - Build 2018.1.131.0	!~ (equivalent to not like)	string	Exclude the results which begin with or contain a given character string. Syntax: !~ following by the string to exclude enclosed in quotation marks. You should use the wildcard character . < string > = exclude what begins with < string >. < string > = exclude what contains < string >. example /groups?search=email!~"group" ==> all the groups by excluding those in which the email* field begins with group /groups?search=email!~"oup" ==> all the groups by excluding those in which the email field contains oup
Oxygen 1.7 - Build 2018.1.131.0	! (equivalent to not)	string	Exclude all results equal to a given character string. Syntax: ! following by the string to exclude enclosed in quotation marks. example /groups?search=email!"group_via_rest@easyvista.com" ==> all the groups by excluding those in which the email field is equal to group_via_rest@easyvista.com
Oxygen 2.1.2 - Build 2018.1.183.0	is_null	string	Retrieve all results in which the field has no value (field value = null) Syntax: Field name following by "is_null" example /groups?search=email:"is_null" ==> all the groups in which the email address has no value
Oxygen 2.1.2 - Build 2018.1.183.0	is_not_null	string	Retrieve all results in which the field has a value (field value = not null) Syntax: Field name following by "is_not_null" example /groups?search=email:"is_not_null" ==> all the groups in which the email address has a value
Oxygen 1.7 - Build 2018.1.131.0	formatDate	string	Format display of Date fields in the HTTP request result. See Description of the options. example /groups?fields=start_date&formatDate=l/M/Y ==> "start_date_format": "Friday/Feb/2023" /groups?fields=start_date&formatDate=l jS \of F Y h:i:s A ==> "start_date_format": "Friday 17th of February 2023 12:00:00 AM"

Fields that could be used in optional parameters

You can use all the fields from the AM_GROUP table.

HTTP status codes for the method

StatusHeader

Note: A Timeout error code will be returned if the server does not respond to the REST Web service request within a given time (by default 60 seconds).

Code	Error		Description

Status400

400

Bad Request

Request could not be run correctly due to malformed syntax.

example

{
"error": "Nothing to update (check fieldnames)"
}

or when the "Suspend a ticket" method is called but the ticket is already suspended. The response returned is: { "error": "The request is already suspended. Operation aborted."}

or when the "Reopen a ticket" method is called but the ticket is not suspended. The response returned is: { "error": "The request is not suspended. Operation aborted."}

Status401

401

Unauthorized

Incorrect authentication process for accessing the resource: Incorrect login/password, invalid session, incorrect Service Manager account.

example

{
"error": "Invalid Login / Password"
}

Example

Result for 3 groups (status code 200)

{
   "HREF": "https://{your_server}/api/v1/{your_account}/groups?max_rows=2",
   "record_count": "2",
   "total_record_count": "219",
   "records": [
        {
           "HREF": "https://{your_server}/api/v1/{your_account}/groups/1",
           "GROUP_EN": "HP Maintenance ",
           "GROUP_FR": "HP Maintenance ",
           "GROUP_GE": "HP Maintenance",
           "GROUP_ID": "1",
           "GROUP_IT": "HP Manutenzione ",
           "GROUP_PO": "HP Manutenção",
           "GROUP_SP": "Mantenimiento de HP"
        },
        {
           "HREF": "https://{your_server}/api/v1/{your_account}/groups/2",
           "GROUP_EN": "Technical Support Netherlands",
           "GROUP_FR": "Support Technique Pays Bas",
           "GROUP_GE": "Technische Unterstützung Niederlande",
           "GROUP_ID": "2",
           "GROUP_IT": "Supporto tecnico Paesi Bassi",
           "GROUP_PO": "Suporte Técnico Holanda",
           "GROUP_SP": "Suporte técnico Países Bajos"
        }
    ]
}

ConventionsAPI

REST API Conventions

Convention		Meaning
Orange		Parameters used in an HTTP request string which do not correspond to Service Manager database fields. example Method View a list of assets https://{your_server}/api/v1/{your_account}/assets?max_rows=3&fields=asset_tag

Black and Bold		Parameters used in the URL of an HTTP request which correspond to Service Manager database fields. example Method View an asset https://{your_server}/api/v1/{your_account}/assets/{asset_id}

Green		Parameters used in the body of an HTTP request which represent JSON object names corresponding to Service Manager database fields; they allow the value of a database field to be assigned or modified. example Method Close an incident/request { "closed": { "end_date": "11/20/2016 12:12:12", } }
Green		Parameters used in the body of an HTTP request which represent JSON object names not corresponding to Service Manager database fields. example Method Reopen an incident/request { "restarted": { "comment": "string (required)" } }

Tags: