Introduction
The search service is a global and shared resource properties repository that is integrated in the IBM Cloud Platform. It's used for storing and searching cloud resource attributes. It categorizes and classifies resources. A resource is controlled and owned by resource providers within the IBM Cloud platform, such as Cloud Foundry, IBM Containers, or Resource Controller. Resources are uniquely identified by a Cloud Resource Naming identifier (CRN). The properties of a resource include tags and system properties. Both properties are defined within an IBM Cloud billing account, and span across many regions.
API endpoint
api.global-search-tagging.cloud.ibm.com
API endpoint
api.global-search-tagging.cloud.ibm.com
API endpoint
api.global-search-tagging.cloud.ibm.com
API endpoint
api.global-search-tagging.cloud.ibm.com
Authentication
REST APIs require the user to specify an OAuth2 security token in the header to be authorized by the IBM Cloud IAM service. You can obtain a bearer token by using the IBM Cloud command line command ibmcloud iam oauth-tokens. Another way to obtain a bearer token is through an API key. For more information, see Getting an IBM Cloud IAM token by using an API key.
Error handling
The resource manager uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response always indicates success. A 400 type response is a failure, and a 500 type response is an internal system error.
| HTTP Error Code | Description | Recovery |
|---|---|---|
200 |
Success | The request was successful. |
400 |
Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. |
401 |
Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. |
403 |
Forbidden | The supplied authentication is not authorized to access '{namespace}'. |
404 |
Not Found | The requested resource could not be found. |
409 |
Conflict | The entity is already in the requested state. |
410 |
Gone | The resource is valid but has been removed already in a previous call |
500 |
Internal Server Error | offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |
Methods
Find instances of resources
Find resources in the internal search platform for a specific account ID. You can optionally apply query strings. To filter results, you can insert a string using the Lucene syntax and the query string is parsed into a series of terms and operators. A term can be a single word or a phrase, in which case the search is performed for all the words, in the same order. To filter for a specific value regardless of the property that contains it, use an asterisk as the key name. Results are filtered by the account ID and IAM subsystem. Only resources that belong to the account ID and that are accessible by the client are returned.
POST /v2/resources/searchCustom Headers
An aplhanumeric string that can be used to trace a request across services. If not specified it will be automatically generated with the prefix "gst-"
Query Parameters
The account ID to filter resources.
Constraints: Value must match regular expression
^[a-fA-F0-9-]+$|^[*]{1}$The maximum number of hits to return. Defaults to 10.
Constraints: 1 ≤ value ≤ 1000
Default:
10A search timeout, bounding the search request to be executed within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.
Constraints: 0 ≤ value ≤ 600000
Default:
0The offset is the index of the item you want to start returning data from. Default is 0.
Default:
0Comma separated properties name used for sorting
Search providers. Supported values are
ghostandims. If not specified, the defaults toghostonly. Specify a single provider.Constraints: length ≥ 1
It contains the query filters, the list of fields to be returned, and the search token (initally set to null or undefined)
The query string
The list of the fields that are returned by the search. The CRN is always returned.
An opaque token. Initially set to null or undefined, then pass the value returned by the previous call
curl --request POST \ --url 'https://api.global-search-tagging.cloud.ibm.com/v2/resources/search?account_id=string&offset=0&limit=10&timeout=0&sort=string' \ --header 'content-type: application/json' \ --header 'accept: application/json' \ --header 'authorization: REPLACE_KEY_VALUE' \ --data '{"query":"string"}'
HttpResponse<String> response = Unirest.post("https://api.global-search-tagging.cloud.ibm.com/v2/resources/search?account_id=string&offset=0&limit=10&timeout=0&sort=string") .header("accept", "application/json") .header("content-type": "application/json") .header("authorization", "REPLACE_KEY_VALUE") .body("{\"query\":\"string\"}") .asString();
var http = require("https"); var options = { "method": "POST", "hostname": "api.global-search-tagging.cloud.ibm.com", "port": null, "path": "/v2/resources/search?account_id=string&offset=0&limit=10&timeout=0&sort=string", "headers": { "content-type": "application/json", "accept": "application/json", "authorization": "REPLACE_KEY_VALUE" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString()); }); }); req.write(JSON.stringify({ query: 'string' })); req.end();
import http.client conn = http.client.HTTPSConnection("api.global-search-tagging.cloud.ibm.com") payload = "{\"query\":\"string\"}" headers = { 'content-type': "application/json", 'accept': "application/json", 'authorization': "REPLACE_KEY_VALUE" } conn.request("POST", "/v2/resources/search?account_id=string&offset=0&limit=10&timeout=0&sort=string", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8"))
The results of the requested search.
The array of results. Each item will represent a resource and will contains all visible properties associated with it.
If false, there is no more data to retrieve on the next page. If true, it's possible that there is more data to retrieve on the next page.
It's set to true if the result is partial of an IAM error when validating user authorization on one or more resources. This field is DEPRECATED and will be removed in future versions of this API
Indicates if the result that's set might be partial or not. Value 0 means the result set is complete. A value greater than 0 means the result set might be incomplete. It's single bits identify the cause. The first bit means the error is in the IAM filter. The second bit means errors are in elasticsearch shards.
Offset parameter specified by the user
Limit parameter specified by the user
The search token to use on the next call.
Status Code
A result paging with the list of resources matching the provided filters.
Bad Request
Unauthorized / Wrong auth token type IAM / Auth token not valid
Unauthorized operation
Internal Server Error / IAM not initialized / Malformed IAM credentials
Search IAM error
System problem or unexpected error
{ "items": { "...": "STRING", "crn": "STRING" }, "more_data": "BOOLEAN", "token": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }
Find instances of resources
'Find cloud foundry resources, resource controlled enabled resources, or storage and network resources running on classic infrastructure in a specific account ID. You can apply query strings if necessary. To filter results, you can insert a string using the Lucene syntax and the query string is parsed into a series of terms and operators. A term can be a single word or a phrase, in which case the search is performed for all the words, in the same order. To filter for a specific value regardless of the property that contains it, use an asterisk as the key name. Only resources that belong to the account ID and that are accessible by the client are returned. You must use this operation when you need to fetch more than 10000 resource items. The /v2/resources/search prohibits paginating through such a big number. On the first call, the operation returns a live cursor on the data that you must use on all the subsequent calls to get the next batch of results until you get the empty result set. By default, the fields returned for every resources are: "crn", "name", "family", "type", "account_id". You can specify the subset of the fields you want in your request.''
POST /v3/resources/searchCustom Headers
An aplhanumeric string that can be used to trace a request across services. If not specified it will be automatically generated with the prefix "gst-"
Query Parameters
The account ID to filter resources.
Constraints: Value must match regular expression
^[a-fA-F0-9-]+$|^[*]{1}$The maximum number of hits to return. Defaults to 10.
Constraints: 1 ≤ value ≤ 1000
Default:
10A search timeout, bounding the search request to be executed within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.
Constraints: 0 ≤ value ≤ 600000
Default:
0Comma separated properties names used for sorting
Constraints: Value must match regular expression
^[+-]?\w+[\w\-\.]*$
It contains the query filters on the first operation call, or the search_cursor on next calls. On subsequent calls, set the search_cursor to the value returned by the previous call. After the first, you must set only the search_cursor. Any other parameter but the search_cursor will be ignored. The search_cursor encodes all the information needed to get the next batch of limit data.
The Lucene-formatted query string. Default to '*' if not set
The list of the fields returned by the search. Defaults to all.
crnis always returned.Constraints: number of items ≥ 1
An opaque search cursor that is returned on each operation call and that must be set on next call.
Constraints: length ≥ 1
curl --request POST \ --url 'https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=string&limit=10&timeout=0&sort=string' \ --header 'content-type: application/json' \ --header 'accept: application/json' \ --header 'authorization: REPLACE_KEY_VALUE' \ --data '{"query":"string"}'
HttpResponse<String> response = Unirest.post("https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=string&limit=10&timeout=0&sort=string") .header("accept", "application/json") .header("content-type": "application/json") .header("authorization", "REPLACE_KEY_VALUE") .body("{\"query\":\"string\"}") .asString();
var http = require("https"); var options = { "method": "POST", "hostname": "api.global-search-tagging.cloud.ibm.com", "port": null, "path": "/v3/resources/search?account_id=string&limit=10&timeout=0&sort=string", "headers": { "content-type": "application/json", "accept": "application/json", "authorization": "REPLACE_KEY_VALUE" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString()); }); }); req.write(JSON.stringify({ query: 'string' })); req.end();
import http.client conn = http.client.HTTPSConnection("api.global-search-tagging.cloud.ibm.com") payload = "{\"query\":\"string\"}" headers = { 'content-type': "application/json", 'accept': "application/json", 'authorization': "REPLACE_KEY_VALUE" } conn.request("POST", "/v3/resources/search?account_id=string&limit=10&timeout=0&sort=string", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8"))
The search scan response
The search cursor to use on all calls after the first one.
Constraints: length ≥ 1
The array of results. Each item represents a resource. An empty array signals the end of the result set, there are no more hits to fetch
Value of the limit parameter specified by the user
Status Code
A result paging with the list of resources matching the provided filters.
Bad Request
Unauthorized / Wrong auth token type IAM / Auth token not valid
Unauthorized operation
Internal Server Error / IAM not initialized / Malformed IAM credentials
Search IAM error
System problem or unexpected error
{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }
Get all supported resource types
Retrieves a list of all the resource types supported by GhoST.
GET /v2/resources/supported_typesNo Request Parameters
curl --request GET \ --url https://api.global-search-tagging.cloud.ibm.com/v2/resources/supported_types \ --header 'authorization: REPLACE_KEY_VALUE'
HttpResponse<String> response = Unirest.get("https://api.global-search-tagging.cloud.ibm.com/v2/resources/supported_types") .header("authorization", "REPLACE_KEY_VALUE") .asString();
var http = require("https"); var options = { "method": "GET", "hostname": "api.global-search-tagging.cloud.ibm.com", "port": null, "path": "/v2/resources/supported_types", "headers": { "authorization": "REPLACE_KEY_VALUE" } }; var req = http.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function () { var body = Buffer.concat(chunks); console.log(body.toString()); }); }); req.end();
import http.client conn = http.client.HTTPSConnection("api.global-search-tagging.cloud.ibm.com") headers = { 'authorization': "REPLACE_KEY_VALUE" } conn.request("GET", "/v2/resources/supported_types", headers=headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8"))
A list of resource types supported by GhoST.
A list of resource types supported by GhoST.
Status Code
List of supported resource types
System problem or unexpected error
{ "code": "STRING", "description": "STRING", "level": "STRING", "message": "STRING", "more_info": "STRING", "response": "STRING" }