REST2 API - Get group information

Hello collective,

I am trying to use the REST2 API to get and update information about RT groups, but am struggling to find documentation or good examples for how to do it. My dev server is on RT 5.0.7.

I can use the groups endpoint, like this test:-

CURL=/usr/bin/curl
RT_URL='https://hostname'
RT_TOKEN='<deleted>'

$CURL --request POST \
    --header "Authorization: token $RT_TOKEN" \
    --no-buffer \
     "${RT_URL}/REST/2.0/groups"

But this lists all groups including role groups, so returns a huge list:

{
   "count" : 20,
   "total" : 81585,
   "per_page" : 20,
   "items" : [
      {
         "type" : "group",
         "_url" : "https://hostname/REST/2.0/group/87",
         "id" : "87"
      },
...
   ],
   "next_page" : "https://hostname/REST/2.0/groups?page=2",
   "pages" : 4080,
   "page" : 1
}

The REST2 documentation suggests this:-

Groups

    GET /groups?query=<JSON>
    POST /groups
        search for groups using L</JSON searches> syntax

    POST /group
        create a (user defined) group; provide JSON content

    GET /group/:id
        retrieve a group (including its members and whether it is disabled)

    PUT /group/:id
        update a groups's metadata (including its Disabled status); provide JSON content

    DELETE /group/:id
        disable group

    GET /group/:id/history
        retrieve list of transactions for group

But then gives no hints on what you need to supply for query in the JSON search to limit the results only to User Defined Groups.(Equivalent of $Groups->LimitToUserDefinedGroups()) in the perl API.

Other scripts I have work for example to for a tickets query:

$CURL ${RT_URL}/REST/2.0/tickets --request POST \
    --header "Authorization: token $RT_TOKEN" \
    --no-buffer \
    --data-binary '
        [
            { "field": "Status",
             "value":  "open"
             },

        ]'

I also want to get customfields from the group, which in Perl API is something like:


my $values = $Group->CustomFieldValues('cust_id');

 while (my $value = $values->Next) {
 my $cust_id= $value->Content;
 print "Cust ID: $cust_id\n";
 }

Any pointers how to do it in the REST2 API would be much appreciated.

Thanks.

So after a bit of poking about in the database and trial and (mostly) error, the secret seems to be a largely hidden field called Domain

$CURL ${RT_URL}/REST/2.0/groups --request POST \
    --header "Authorization: token $RT_TOKEN" \
    --no-buffer \
    --data-binary '
        [
            { "field": "Domain",
              "value": "UserDefined"
             }

        ]'

This returns only the user defined groups.

With some further experimentation, it’s possible to add the “hidden” fields and the group custom fields to the JSON output by adding fields= to the URL, like so:

$CURL ${RT_URL}/REST/2.0/groups?fields=Name,Description,Domain,CustomFields --request POST \
    --header "Authorization: token $RT_TOKEN" \
    --no-buffer \
    --data-binary '
        [
            { "field": "Domain",
              "value": "UserDefined"
             }
        ]'
{
   "items" : [
      {
         "_url" : "https://hostname/REST/2.0/group/98686",
         "id" : "98686",
         "type" : "group",
         "Description" : "Test Customer Group",
         "Name" : "Customer Test",
         "Domain" : "UserDefined",
         "CustomFields" : [
            {
               "values" : [
                  "123"
               ],
               "_url" : "https://hostname/REST/2.0/customfield/16",
               "name" : "cust_id",
               "id" : "16",
               "type" : "customfield"
            }
         ]
      },
      {
         "CustomFields" : [
            {
               "values" : [],
               "name" : "cust_id",
               "type" : "customfield",
               "id" : "16",
               "_url" : "https://hostname/REST/2.0/customfield/16"
            }
         ],
         "Domain" : "UserDefined",
         "Description" : "Accounts Staff",
         "Name" : "Accounts",
         "id" : "8436",
         "type" : "group",
         "_url" : "https://hostname/REST/2.0/group/8436"
      },
      {
         "id" : "101633",
         "type" : "group",
         "_url" : "https://hostname/REST/2.0/group/101633",
         "Description" : "Comms",
         "Name" : "Comms",
         "CustomFields" : [
            {
               "name" : "cust_id",
               "type" : "customfield",
               "id" : "16",
               "_url" : "https://hostname/REST/2.0/customfield/16",
               "values" : []
            }
         ],
         "Domain" : "UserDefined"
      },

[...]

It’s picky about case. If I set fields=Domain but in the query do lower case:

        [
            { "field": "domain",
              "value": "UserDefined"
             }

        ]'

Then the field displays but the query doesn’t match. Some things for “Domain” are written with “RT::”, e.g. RT::System-Role but UserDefined is not. So searching for RT::UserDefined doesn’t work. A bit inconsistent.

I do wish RT had more extensive and easier to understand documentation with better examples, especially the API. It would lead to a more positive experience and less tearing my hair out! Several hours I won’t get back, trying figure out how to do a simple thing.

There doesn’t seem to be a way to ask it to display all fields, which may have saved quite a lot of time in this case!

1 Like

When trying to use the REST2 API, I’ve found the test cases invaluable for getting examples. I’ve also found features missing every now and again and had to write them…

What we noticed recently in an upgrade from 5.0.1 to 5.0.5 is that the paging information is often missing if the user doing the REST2 call doesn’t have rights to all the results. The docs do mention this but they say that next_page should still work. Unfortunately next_page often seem to be absent even if there should be more results. We’ve “fixed” it by increasing the rights of the API user so they can see all the results with normal paging, but I need to dig into the code to find out why its behaving like it is. A bit of an annoying change in the API behaviour!

Yeah, that’s an annoying and unfortunate change, agreed!

There is a bug fix (commit b905d03cfbff7e59e68613da614f571302cf175a ) which fixes next_page not being returned, which is in 5.0.6. You can probably cherry pick that if you can’t upgrade to 5.0.6 (or 5.0.7).

1 Like

Just tried a REST2 call on one of our 5.0.7 installations, and it seems to be doing something similar: I get:

          'count' => 14,
          'page' => 1,
          'total' => undef,
          'pages' => undef,
          'per_page' => 20

with 14 hits and no next_page when doing a /queues/all with the default 20 hits per page.

However if I set the per_page attribute in the query to 100 (the max), I get 76 hits but still no next_page entry:

          'total' => undef,
          'pages' => undef,
          'per_page' => 100,
          'page' => 1,
          'count' => 76

So something isn’t right even on 5.0.7 by the looks of things.

Does the user you’re using have access to see all the queues? If the only change is to per_page, then that smells like a nasty bug.

No, they’re a “normal” user, not one with superuser access that can see everything. We’ve got north of 100 (enabled, active) queues on that server and they won’t be see all of them.

I’ll probably have to do some more tests on one of our dev servers, but I’m a bit busy with other, non-RT stuff at the moment so as we’ve got a work around it hasn’t drifted to the top of the “to do” pile yet. :slight_smile:

I did look in the tests e.g groups.t

  • I learned a few things - (probably more about the Perl API!). Still didn’t have any hints on how to get user defined groups though.

I started a new page in the wiki: REST2 - Request Tracker Wiki to start collecting some tips and examples where there are gaps in the documentation.

3 Likes

Top job! That’s really helpful - thank you. :+1: