API View Model

The DevOps Secrets Safe API is written according to OpenAPI standards and enables end users to view documentation for the API using Swagger UI. A preconfigured Swagger UI is available as part of the solution (https://<secrets-safe-ip-dns>/swagger).

The version-specific Open API specification is included with the deployment files as dss-openapi.json.

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 discovered. A value of 1 returns the element specified and all direct child elements. A value of 2 returns all child and grandchild elements of the element discovered.
  • Pagination: Pagination consists of two options:
    • Page Size: The number of records to return for the direct child elements of the element discovered. Values must be between 1 and 100.

All grandchild elements of the element discovered are also limited to this page size if it is specified; otherwise, it is limited to the maximum page size of 100.

    • Page Number: The page number (1-based) of results to return.
  • Sorting: Specifies the sort order to use with the elements 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 100 (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: asc or desc) specified in brackets after each.
  • Name(desc) OR Name(desc),Url(asc)

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

This displays usage examples, and examples and details for optional arguments, for the command.

ssrun user get -h

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:

This displays usage examples, and examples and details for optional arguments, for the command.

ssrun safelist get -h

Displayed results of ssrun command: Usage examples and optional arguments.

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 discovered results.
  • PageCount: The page number of the returned results.
  • PageSize: The total the number of the returned results.
  • TotalSize: The total number of existing elements.
 This command returns a result with a page size of 10, the second page of the result set, and sorts 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 this example, the paging information informs us that there are a total of 15 pages available for discovery (given the page size we specified), and there are a total of 147 users.

For more information about the Swagger UI, please see Swagger UI.