Sample Search and Navigation REST API requests using cURL
This section provides several examples of how common Search and Navigation REST API requests can be made through the cURL
command-line utility.
For general information about how to make requests, see Understand how to execute endpoints.
Note: Oracle does not recommend the use of any particular UI tool or utility for making REST API calls.
Log in and get an access token
Use the following POST request to log in to the Admin API on the Oracle Commerce administration server, using an account that has the Administrator role:
curl -X POST
-- data "grant_type=password&username=user_name&password=password&totp_code=
passcode" http://host:port/ccadmin/v1/mfalogin > /pathname/filename.txt
Note that the request must include a user name, password, and passcode. To obtain passcodes, the login account must be registered with the Oracle Mobile Authenticator app. See Access the Commerce administration interface for more information.
This POST request returns an OAuth
access token, which you must provide in the authorization headers of all other requests. The following is an example of an access token, greatly abbreviated:
"token_type":"bearer","access_token":"Authorization:Bearer
eyJhbGciOiJSUzI1NiIsImprdSI6IjVkYmQyTA4MC9jY2FkbWluL=="
where eyJhbGciOiJSUzI1NiIsImprdSI6IjVkYmQyTA4MC9jY2FkbWluL==
is the OAuth
access token (abbreviated) that you must use in the authorization headers of other requests.
Note: Because the OAuth
access token returned by this request must be used by all other requests, it is convenient to redirect it to a text file, as shown in the example above. The access token can then be copied from the text file into the other requests.
Export configuration of a search resource
Issue a GET command to export configuration of a search resource. Note that GET is the default command and need not be specified.
For example, the following request exports the configuration of the search interface named ALL. The exported JSON content is displayed on the screen, immediately beneath the command line:
curl [-X GET] -H "Authorization:Bearer access_token"
http://host:port/gsadmin/v1/searchInterfaces/All.json
{
"ecr:lastModifiedBy": "admin",
"ecr:lastModified": "2016-10-17T05:25:35.764-07:00",
"ecr:createDate": "2016-10-17T05:25:35.764-07:00",
"ecr:type": "search-interface",
"crossFieldMatch": "always",
"fields": [
{"attribute": "product.displayName"},
{"attribute": "sku.displayName"},
{"attribute": "parentCategory.displayName"},
{"attribute": "product.brand"},
{"attribute": "parentCategory.keywords"},
{"attribute": "sku.description"},
{"attribute": "product.description"},
{"attribute": "product.category"},
{"attribute": "ecr:crossField"},
{"attribute": "product.longDescription"},
{"attribute": "product.repositoryId"}
]
The following request redirects the exported configuration of the search interface All
to a file:
curl [-X GET] -H "Authorization:Bearer access_token"
http://host:port/gsadmin/v1/searchInterfaces/All.json > /pathname/filename.txt
The following request exports the configuration of the search interface All
in a ZIP file:
curl [-X GET] –H "Authorization:Bearer access_token"
http://host:port/gsadmin/v1/searchInterfaces/All.zip -o pathname/filename.zip
where:
–o (lower case) pathname/filename.zip
causes the ZIP file specified by filename to be downloaded to the location specified by pathname.
Note: ZIP format exports not only the configuration of the specified object to be exported, but also the configuration of all its child objects, in separate _.json
files. JSON format, in contrast, exports only the configuration of the specified object to be exported.
Create a search resource
In JSON format, use the following POST request to configure the searchInterfaces
folder. The configuration to be imported is provided in a JSON file:
curl -X POST -H "Authorization:Bearer access_token"
–d@pathname/filename.json
–H "Content-Type:application/json"
http://host:port/gsadmin/v1/searchInterfaces
In ZIP format, use the following POST request to configure the searchInterfaces
folder. The configuration to be imported is provided in a ZIP file. The ZIP file must contain a file named _.json
:
curl -X POST -H "Authorization:Bearer access_token"
–F ":file=@pathname/filename.zip"
http://host:port/gsadmin/v1/searchInterfaces
Note: When the POST request is executed in JSON format, the POST request can create a resource but not overwrite an existing resource. When the POST request is executed in ZIP format, the POST request can either create the resource or overwrite it if it already exists.
Modify a search resource
Use the PATCH method to add attributes to an object or change the values of existing attributes in the object. The PATCH method can be used only in JSON format.
For example, the following PATCH request can modify the values of existing attributes of a thesaurus-entry
object, or add new attributes to that object:
curl -X PATCH -H "Authorization:Bearer access_token"
–d@pathname/filename.json
-H "Content-Type:application/json"
http://host:port/gsadmin/v1/thesaurus/my-thesaurus-entry
Replace configuration of a search resource
All
; in this example, the configuration containing the replacement is provided in a JSON file named SearchInterface_put.json
:curl -X PUT -H "Authorization:Bearer access_token"
-d@pathname/SearchInterface_put.json
-H "Content-Type:application/json"
http://host:port/gsadmin/v1/cloud/searchInterfaces/All
In ZIP format, execute the following command to replace existing configuration of the search interface All
; in this example, the configuration containing the replacement is provided in a ZIP file named temp.zip
:
curl -X POST -H "Authorization:Bearer access_token"
-F ":file=@temp.zip"
http://host:port/gsadmin/v1/cloud/searchInterfaces/All
Install cURL
The examples within this chapter use the cURL
command-line tool to
demonstrate how to access the Commerce Search and Navigation REST API. To connect securely to a server, you must install a
version of cURL that supports SSL.
The following procedure demonstrates how to install cURL
on a Windows 64–bit system.
- In your browser, navigate to the
cURL
home page athttp://curl.haxx.se
and click Download in the left navigation menu. - On the
cURL
Releases and Downloads page, locate the SSL-enabled version of thecURL
software that corresponds to your operating system, click the link to download the ZIP file, and install the software.
You are now ready to send requests to the Commerce Search and Navigation REST API using cURL
.
This table summarizes the cURL
options used in the command examples.
cURL Option | Description |
---|---|
-d, --data @filename.json |
Identifies the request document, in JSON format, on the local machine. |
-H |
Defines one or both of the following:
|
-o, --output filename |
Writes output to a file instead of stdout |
-X |
Indicates the type of request (for example, GET, POST, and so on). |
For example:
curl -X GET -H <request-header>:<value>
https://<subdomain>.<domain>.com/<path>/resource-path>