V-Spark Online Help

Using GET with cURL and the /config API

This section discusses how to use the /config API to retrieve configuration information from a specified V‑Spark installation. A sample cURL command to retrieve information about all of the organizations in a V‑Spark installation is the following:

curl -s $PROTOCOL://$HOST:$PORT/config/orgs?token=TOKEN

The variables in this command are the following:

Table 1. cURL command variables

Name

Type

Values

Description

PROTOCOL

http (default), https

The protocol that your V‑Spark installation uses to communicate over the network.

HOST

host name or IPv4 IP address

The host on which your V‑Spark installation is running.

PORT

The network port that the V‑Spark installation is listening on. The default is port 3000, which must still be specified in V‑Spark REST API calls.

TOKEN

An authorization token that enables calls to the /config API to access all data in a V‑Spark installation. If you are using cURL to use the API to retrieve or modify information that is associated with a specific company, you can provide that company's authorization token to authorize your access. If you are requesting higher-level information, you can always use the V‑Spark installation's root token to obtain the information that you are requesting. The root token for a default V‑Spark installation is located in the file /opt/voci/state/vspark/apitoken. Finding a company's authorization token is shown in V‑Spark API Permission Requirements.



Note that no REST method (GET, POST, DELETE) has been specified in the preceding cURL command. That is because the cURL command defaults to performing a GET operation when no REST method is specified.

As an example, the cURL command to use the HTTP protocol to retrieve configuration information for the organizations that have been defined in a V‑Spark installation on the host example.company.com is the following:

curl -s http://example.company.com/config/orgs?token=123456789012345678901234567890123

The previous cURL commands retrieved information about all of the organizations within an entire V‑Spark installation, and therefore required providing the root token for that installation. To retrieve information about organizations within a specific company, you can use that company's token, so an example would be the following:

curl -s http://example.company.com/config/CO_SHORT/orgs?token=company-token

See V‑Spark API Permission Requirements for information about retrieving the type of token that you want to use.

When calling the config API and providing entries that you want to create or modify in JSON format, you must make sure that you are calling the API with JSON that corresponds to the URL that you are specifying. For example, the /config/users API can also be called as /config/CO_SHORT/users to get information about the users within a specific company. When calling the /config/users API to create or modify user information, the user information must be top-level JSON information about the company with which you want to associate the user, as shown in the following sample JSON.

Figure 1. Sample User JSON for use with the /config/users API
"DocTestCo": {
    "test.user.07": {
        "name": "Another Automated Test User",
        "email": "test.user.07@example.com",
        "company": "DocTestCo",
        "auth": {
            "verified": false,
            "disabled": false,
            "method": "standard"
        },
        "permissions": {
           "DocTestCo": {
              "all": [
                 "read",
                 "write"
               ]
            }
         }
     }
}


When calling the /config/CO_SHORT/users API to create or modify user information, the user information must be top-level JSON information about the user, and does not need to nest the user information within the company information, because you are specifying the company that the user is associated with as part of the URL.

The following sample JSON shows the same information about a user as the previous example, except that the sample below does not nest the user information within a company identifier.

Figure 2. Sample User JSON for use with the /config/CO_SHORT/users API
 {
   "test.user.07": {
       "auth": {
          "disabled": false,
          "verified": true,
          "method": "standard"
       },
       "company": "DocTestCo",
       "email": "test.user.07@example.com",
       "name": "Another Automated Test User",
       "permissions": {
           "DocTestCo": {
               "all": [
                   "read",
                   "write"
               ]
           }
       }
   }...
 } 


If you deliver JSON at the wrong level to any V‑Spark API, you will receive an error code (400). Ensuring that you have sent the level of JSON that corresponds to the API URL call that you are making is the first thing that you should check when an API call is failing and you are sending JSON that you know to be valid.