API View Model

View Model Options

The DevOps Secrets Safe View Model consists of the following options:

  • Verbosity: When used, returns a full attribute listing of whatever element is being discovered. Otherwise, a slim view of the element is returned.
  • Depth: The maximum depth of the view to return. A value of 0 returns only the element being discovered. A value of 1 returns the element specified and all direct children. A value of 2 returns all children and grandchildren of the element being discovered.
  • Pagination: Pagination consists of two options:
    • Page Size: The number of records to return for the direct children of the element being discovered. Values must be between 1 and 500.

All grandchildren of the element being discovered will also be limited to this page size if it is specified, otherwise, it will be limited to the maximum page size of 500.

    • Page Number: The page number (1-based) of results to return.
  • Sorting: Specifies the sort order to use with the elements being discovered.

View Model Usage

Each sub command get operation supports all or some subset of the following view model options:

  • -v, --verbose: Verbosity is optional and defaults to false.
  • -d, --depth: Depth is optional and defaults to 1.
  • -ps, --page-size: Page size is optional and defaults to 50. Invalid values are forced within the range of 1 and 500 (maximum page size).
  • -pn, --page_number: Page number is optional and defaults to 1. Invalid values are forced within the range of 1 and the total page count.
  • -sb, --sort-by: Sorting is optional, and by default, no sorting is applied. This is defined as a single field or comma delimited list of fields with the sort order (one of: ace or desc) specified in brackets after each.

Name(desc) OR Name(desc),Url(asc)

To determine what options are supported for each sub command get operation, use the -h (help) flag.

$ssrun user get -h 

Usage: ssrun user get [-h] [-n USERNAME] [-i IDENTITY_PROVIDER] [-v] [-ps PAGE_SIZE] [-pn PAGE_NUMBER] [-sb SORT_BY]

optional arguments:
	-h, --help              : Show this help message and exit.
	-n, --name              : If a name is specified, only that user is returned and 
				sorting and pagination options are ignored. If no name is
				specified, a list of users is returned with sorting and 
				pagination options (if specified) applied.
	-i, --identity-provider : Identity provider name. Defaults to internal if not 
				specified.
	-v, --verbose           : Verbose output. Use the -v flag to get a full listing of 
				users attributes. Otherwise, a slim view of each user is
				returned.
	-ps, --page-size        : Specifies the maximum number of elements to return in the 
				user listing. Value must be between 1 and 500. All
				membership or group listings are also limited to this page 
				size.
	-pn, --page_number      : Specifies the page number (1-based) of results to return.
	-sb, --sort-by          : Specifies the sort order for the users list. This is
				defined as a single field or comma delimeted list of fields 
				with the sort order (one of:ace|desc) specified in brackets
				after each. For example: Name(desc) OR Name(desc),Url(asc).

In the above example, the get operation for the user sub command does not support the depth option. Whereas, it does for the safelist sub command:

$ ssrun safelist get -h 

optional arguments:
	-h, --help          : Show this help message and exit.
	-n, --name          : If a name is specified, only that safelist is returned and 
			    sorting and pagination options are ignored. If no name is 
			    specified, a list of safelists is returned with sorting and 
			    pagination options (if specified) applied.
	-v, --verbose       : Verbose output. Use the -v flag to get a full listing of 
			    safelist and IP range attributes. Otherwise, a slim view of 
			    each safelist and ip range is returned.
	-d, --depth         : The maximum depth of the view to return. A value of 0 returns 
			    only the element specified. A value of 1 returns the element 
			    specified and all direct children. A value of 2 returns all
			    children and grandchildren of the element specified.
	-ps, --page-size    : Specifies the maximum number of elements to return in the 
			    safelist listing. Value must be between 1 and 500. All IP range 
			    listings are also limited to this page size.
	-pn, --page_number  : Specifies the page number (1-based) of results to return.
	-sb, --sort-by      : Specifies the sort order for the safelist list. This is 
			    defined as a single field or comma delimeted list of fields with 
			    the sort order (one of:ace|desc) specified in brackets after each. 
			    For example: Name(desc) OR Name(desc),Url(asc).

Discovery Results

When paging is applied to a result set, the output always contains the following block of pagination information:

"Paging": {
	"CurrentPage": 1,
	"PageCount": 15,
	"PageSize": 10,
	"TotalSize": 147
}
  • CurrentPage: The current page of the results that were discovered.
  • PageCount: The page number of the results that were returned.
  • PageSize: The total the number of results that were returned.
  • TotalSize: The total number of elements that exist.

In the example below, we are specifying that we want to use a page size of ten, that we want to view the second page of that result set, and we want to sort the results in ascending order by name:

$ ssrun user get -ps 10 -pn 2 -sb 'Name(asc)' 

{
	"Uri": "/principal/internal/user",
	"Users": [
		{
			"Uri": "/principal/internal/user/Berta"
		},
		{
			"Uri": "/principal/internal/user/Bob"
		},
		{
			"Uri": "/principal/internal/user/Boomer"
		},
		{
			"Uri": "/principal/internal/user/Brad"
		},
		{
			"Uri": "/principal/internal/user/Brenda"
		},
		{
			"Uri": "/principal/internal/user/Catherine"
		},
		{
			"Uri": "/principal/internal/user/Cathy"
		},
		{
			"Uri": "/principal/internal/user/Chloe"
		},
		{
			"Uri": "/principal/internal/user/Chris"
		},
		{
			"Uri": "/principal/internal/user/Cicilia"
		}
	],
	"Paging": {
		"CurrentPage": 2,
		"PageCount": 15,
		"PageSize": 10,
		"TotalSize": 147
	}
}

In the above example, the paging information lets us know that there are a total of 15 pages available for discovery (give the page size we specified), and there are a total of 147 users.