Installing and using curl
Most examples provided by the SoftExpert Suite documentation use curl, an efficient and user-friendly computer software project designed to send HTTP requests without need for a web browser. With curl, you can try different API calls through a command line interface, whether using the Windows command prompt, the macOS terminal, or Linux. You do not need to build a functional web application to use the APIs.
curl operates similarly to a web browser, sending HTTP requests. To request a web page from a command line, just type curl followed by the desired URL address:
The response from the web server is shown directly in your command line interface. If you have requested an HTML page, you will get the page source, which is what a browser normally reads.
β― Disclaimer: SoftExpert Suite does not support third-party technologies, such as curl, Windows, MacOS, or Linux. For assistance, refer to the supplier's manual.
Using curlβ
You can use curl to inspect and test different SoftExpert Suite API requests without having to create a functional web application. For example, the following curl statement sends an HTTP request to the SoftExpert Document API:
curl 'https://my-domain.softexpert.com/apigateway/v1/document/view' \
-d '{"iddocument": "<id_document>"}' \
-H 'Content-Type: application/json' \
-v -H 'Authorization: <your_api_token> ' -X POST
The API returns a JSON object that returns information from the queried document located in SoftExpert Document.
{
"return": {
"IDDOCUMENT": "007008",
"NMTITLE": "SoftExpert Suite 2.2 - Integration Guide",
"IDCATEGORY": "007",
"NMCATEGORY": "Information technology",
"STATUS": "2",
"NRHITS": "0",
"NMAUTHOR": "Jorge Benitez",
"IDREVISION": "00",
"DTDOCUMENT": "17/04/2023",
"RESUME": "SoftExpert Suite Integration Guide.",
"URL": "https://my-domain.softexpert.com/se/v19666/document/dc_view_document/api_view_document.php?cddocument=615",
"LINKSHARE": " ",
"ATTRIBUTTES": {
"item": {
"ATTRIBUTTENAME": "ATRNF07",
"ATTRIBUTTEVALUE": {
"document": ""
}
}
},
"ELECTRONICFILE": {
"item": {
"FILENAME": "DT22.PT0007 - 00 - DOCUMENTATION-2.2-PT_BR-Guia de integração.pdf"
}
}
}
}
JSON (JavaScript Object Notation) is a compact and efficient format for exchanging information between systems. Its structure was designed to make it easier for humans to read and write, while providing easy analysis and data generation for machines.
Using curl on Windowsβ
You can use the Windows command prompt to execute the curl examples. To launch the command prompt, open the Start menu, type cmd in the search box and press Enter.
From Windows 10 build 17063, curl has become a standard component of the operating system. Thus, all Microsoft Windows 10 and Windows 11 installations, as of then, include curl by default in their configuration.
The examples in the documents need to be slightly modified in order to work
correctly on Windows. First, replace any end-of-line backslash character (\)
with the caret character (^)
. Then, if an example contains JSON data, move the
data to a file before executing the example. The following sections provide more
details.
Replacing end-of-line backslashesβ
curl examples often have a backslash (\)
at the end of the lines to break up a
long statement into easier-to-read lines. The backslash is a line continuation
character in UNIX, but not in Windows. In Windows, replace any backslash at the
end of the lines with the caret character (^)
, which is an escape character in
Windows. Do not leave any spaces after any ^
character, or it will not work.
The cursor will escape the space instead of the new line.
Example:
url https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d '{"iddocument": "DT22.PT0007"}' ^
-H 'Content-Type: application/json' ^
-v -H 'Authorization: <your_api_token> ' -X POST
You can paste a multi-line statement into the command prompt by clicking the icon in the upper left corner and selecting Edit -> Paste . If you prefer to use the keyboard, press Alt + spacebar to open the menu, and press E and P.__
Moving JSON data to a fileβ
The Windows command prompt does not support single quotes. It is a problem because curl statements use single quotes to specify JSON data. Example:
curl https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d '{"iddocument": "DT22.PT0007"}' ^
-H "Content-Type: application/json" ^
-v -H 'Authorization: <your_api_token> ' -X POST
The statement specifies JSON data to create a group (the -d
option means
date). Since the JSON is enclosed in single quotes, the statement will not
work on the command line.
To fix this issue, save the JSON to a separate file and import it into the curl statement. To modify the example above, create a file called json.txt containing the following text:
{ "iddocument": "DT22.PT0007" }
Then change the curl statement to import the JSON data with the @filename syntax:
curl https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -H 'Authorization: <your_api_token> ' -X POST
Before executing the statement, use the cd
(change directory) command to
navigate to the folder containing the file. Example:
C:\> cd json_files
Then paste the curl statement into the command prompt:
curl https://my-domain.softexpert.com/apigateway/v1/document/view ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -H 'Authorization: <your_api_token> ' -X POST
An alternative to not having to move the JSON to a separate file is to use
double quotes around the JSON data in the curl
statement and escape the
internal ones with backslashes:
-d "{\"group\": {\"name\": \"My Group\"}}" \
It does not end there. The following special characters in strings must be
escaped with the caret character (^): &, \, <, >, ^, |
.
Therefore, if the file to be imported contains one of these characters, you will have to escape them.
This is tedious and error-prone. It is best to continue importing the JSON from a file.
Installing curlβ
MacOSβ
curl is installed by default on macOS. To try it, see the Testing your curl installation topic below.
To check the installed version, run curl --version
.
Windows 10/11 after build 17063β
To check whether curl is installed, open the command prompt and type the
curl -V
command. If the command is recognized, curl is installed.
More recent Windows builds already have curl installed by default. But you candownload a graphical installer. After that, curl should be in your PATH and ready to be used by CMD or PowerShell.
Linuxβ
curl may or may not come pre-installed in a Linux distribution, depending on the distribution. Some popular distributions, such as Ubuntu, Debian, and CentOS, usually include curl by default, while others may include it.
If you need to check whether curl is installed on your system, you can run the following command in the terminal:
curl --version
If curl is installed, the command returns the installed version. If it is not, you will receive an error message, and curl will have to be installed.
To install curl on Ubuntu or Debian, you can use the following command:
sudo apt update && sudo apt install curl
To install curl on CentOS, Fedora or RHEL, use:
sudo yum install curl
Or, for more recent Fedora versions, use:
sudo dnf install curl
Keep in mind that installation commands may vary depending on the Linux distribution you are using.
Testing your curl installationβ
You can test your curl installation by sending a request to the SoftExpert Suite API. The test retrieves information from a SoftExpert Document document.
Testing curl
- Paste the following curl statement into your favorite text editor:
curl 'https://my-domain.softexpert.com/apigateway/v1/document/view' \
-d @json.txt ^ \
-H 'Content-Type: application/json' \
-v -H 'Authorization: <your_api_token>' -X POST
Windows users: Replace the line continuation backslash character (\)
with
a caret character (^)
. Make sure there is no space after the cursor. Refer to
the Using curl on Windows topic above.
- Replace the placeholders in curly brackets with your user token and the ID # of the SoftExpert Document document in the json.txt file. Example:
curl "https://my-domain.softexpert.com/apigateway/v1/document/view" ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -H "Authorization: eyJhbG..." -X POST
Example of the .txt
file located in C:\> cd json_files
:
{ "iddocument": "007008" }
- Launch your command line interface.
- On Windows, open the Start menu, typecmd in the search box, and pressEnter.
- On macOS, double-click the Terminal application in the Applications/Utilities folder. You can also press the Command + Space keys to open the Spotlight search, and type "Terminal" to find it faster.
- Copy the curl statement from your text file and paste it into the command prompt.
Windows users: After pasting it to the clipboard, select Edit > Paste from the context menu in the upper left corner of the window:
- Press Enter to execute the curl statement.
The console should display the SoftExpert Document information formatted as a JSON object.
You can print the results for easier reading.
Common curl command line optionsβ
-H
or--header
: Specifies any extra header content to be included in the HTTP
request. API requests that send data to our servers typically include the
content type of the data. Example:
Example: -H "Content-Type: application/json"
.
-v
or --verbose
: Makes the response more detailed.
-X
or --request
: Specifies the request method to use when communicating with
the HTTP server.
Example: -X PUT
or -X POST
.
-d
or --date
: The -d
option allows specifying the data to be sent in the
request body, either in string format or in a file.
Example:
{ "iddocument": "<id_document>" }
-L
or --location
: Used to automatically follow HTTP redirects.
-o
or --output
: Used to save the server response to a file.
For other curl command line options, see the official documentation here.