Retrieval of software components (v2)

9.2.14 Available from 9.2.14.

You use the GET operation on the api/sam/v2/software_components element to request information about software components in your catalog. The API returns details of existing components as well as historical data about components that were removed.

Permissions

An icon representing a user. You must have the View Software Catalog and Signatures permission to perform this task.

Resource URL

https://hostname:port/api/sam/v2/software_components

Resource information

Table 1. Resource information
Operation details Description
HTTP method GET
Request headers
Accept-Language (optional)
  • Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
  • Values: en-US (only English is supported)
Token
  • Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests.
  • Values: an alphanumeric string that is generated in License Metric Tool
Request format application/json
Response headers
Content-Type
  • Use: Specifies the content type of the response.
  • Values: application/json
Content-Language
  • Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language.
  • Values: en-US, …
Response payload Software Components element
Response format application/json
Response codes

200 – OK

500 – “Bad Request” if a query parameter contains errors or is missing

Schema description

To retrieve the list of all columns that are returned by this REST API together with their descriptions, use the following request.
GET https://hostname:port/api/sam/v2/schemas/software_component.json

Available columns

Table 2. Available columns
Column Description Displayed by default Type
id Identifier of the component instance. Numeric
name Name of the component. String
release Release of the component. String
guid Component GUID. String
is_ibm Information whether the component is provided by IBM.   Boolean

Applicable associations

You can additionally retrieve data from the following associations:

Query parameters

Table 3. Query parameters
Parameter Description Required Value
columns[] Specify which columns to retrieve. If you do not specify this parameter, only default columns are retrieved.
Example: Retrieve component name and id
URL?columns[]=name&columns[]=id
  String
order Specify how to sort the returned data. The default direction for sorting columns is ascending. If you want to specify a descending sort, append desc to the column name.
Example: Order by component ID descending
URL?order[]=id desc
  Alphanumeric
limit Specify the number of rows to retrieve. If you omit this parameter, all rows are retrieved.
Example: Retrieve 100 records
URL?limit=100
  Numeric
offset Specify the number of rows to skip for retrieving results. You can use it together with the limit parameter to paginate results.
Example: Retrieve 50 records starting after record 150
URL?limit=50&offset=150
  Numeric
criteria Retrieve records which match specific conditions. The parameter should have the following structure, written in one line:
<criteria> ::= <left-brace> <boolean-operator> <colon> <left-bracket> 
<criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace>
<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> ::= <json-array> | <json-string> | <json-number> | <json-null>

For more information about operators, see: Common connectors and operators.

  String

Example conversation - default columns

Request
GET https://hostname:port/api/sam/v2/software_components
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"id":1,
"name":"DB2 8.1",
"release":8,
"guid":"XYZ",
"is_ibm":1,
}]

Example conversation - association

Request
GET https://hostname:port/api/sam/v2/software_components
?columns[]=id&columns[]=name&columns[]=tags.name
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"id":1,
"name":"DB2 8.1",
"tags":
[{"name":"ibm"}]
}]