Helix Swarm Guide (2020.1)

Search: Swarm search

Search Redis cache for users and groups

Summary

Search the Redis cache for users and groups.

GET /api/v10/search?term=<term>&context=user,group

Description

Search the Redis cache for userids, full names, groupids, and group names. Results are returned in alphabetical order and the search is case insensitive.

Parameter Description Type Parameter Type Required

term

Specifies the characters to search for. Searches are case insensitive.

string

path

Yes

context

Limit the search results, valid context values are user and group. Separate context values with a comma (,).

string

path

Yes

starts_with_only

Options are:

  • true: searches for users/groups that start with the search term. This results in a faster search than when this parameter is set to false.
  • false: searches for the term anywhere in users/groups. This is the search used if starts_with_only is not included in the request.

boolean

path

No

limit

Limit the combined maximum number of search results returned for users and groups. Search results are balanced across the contexts requested and will never return more results than the specified limit.

Examples: based on a search that results in 8 user matches and 30 group matches before the limit is applied:

  • limit=7 and context=user: search result is limited to 7 users.
  • limit=6 and context=user,group: search result is limited to 3 users and 3 groups.
    An even limit value splits the search result limit evenly between the specified contexts.
  • limit=7 and context=user,group: search result is limited to 4 users and 3 groups.
    An odd limit value splits the search result limit unevenly between the specified contexts with the higher number applied to the first context in the list.
  • limit=20 and context=user,group, search result is limited to 8 users and 12 groups.

Search results are not limited when the limit parameter is excluded from the request.

integer

path

No

ignoreBlacklist

Options are:

  • true: the userBlacklist and groupBlacklist filters are ignored and are not applied to the search results.
  • false: applies the userBlacklist and groupsBlacklist filters to the search results. This is the search used if ignoreBlacklist is not included in the request.

boolean

path

No

Example usage

Search users and groups starting with "jo" with a limit of 3 results returned

Search users and groups starting with "jo" with a limit of 3 results returned.

curl -u "username:ticket" "https://myswarm-url/api/v10/search?starts_with_only=true&term=jo&context=user,group&limit=3"

Swarm responds with:

HTTP/1.1 200 OK 

{
  "error": null,
  "messages": [],
  "data": {
    "user": [{
        "User": "joakly",
        "FullName": "Jane Oakly"
      },
      {
        "User": "jsmith",
        "FullName": "John Smith"
      }
    ],
    "group": [{
      "Group": "jogd",
      "name": "JOGD"
    }],
    "limit": 3
  }
}

Search groups for "admin" anywhere in group names and groupids

Search for "admin" anywhere in group names and groupids with no limit on the number of results returned by the search.

curl -u "username:ticket" "https://myswarm-url/api/v10/search?context=group&term=admin"

Swarm responds with:

HTTP/1.1 200 OK 

{
  "error": null,
  "messages": [],
  "data": {
    "group": [
      {
        "Group": "swarm-admin",
        "name": "Swarm-admin"
      },
      {
        "Group": "jplugin-admin",
        "name": "JPlugin-Admin"
      },
      {
        "Group": "administrators",
        "name": "Administrators"
      },
      {
        "Group": "sysadmins",
        "name": "Sysadmins"
      }
    ]
  }
}

If a request fails

<error code>:

    422 Parameter not specified or invalid, the error message in the response contains the error details.

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
}