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.

caution

  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

1. 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.

2. 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" }

3. 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.

4. 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:

5. 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.