cURL

cURL is a command line tool that can perform HTTP requests (​https://curl.haxx.se/). With this tool the low level JSON over HTTP API of CLOUDFLOW is exposed.

To perform an API call using cURL, follow these steps:

1. Retrieve the contents of an HTTP request with a JavaScript command.

In order to perform an API call with a cURL command line, you first need to inspect the content of the HTTP request with a JavaScript command. The returned data are then used in cURL.

To do this, follow these steps:
  1. Log in to CLOUDFLOW with Google Chrome.

    The reason for this is that the CLOUDFLOW UI uses the API to show the pages, so you can perform API calls with the JavaScript console. Google Chrome is a perfect browser for this.

  2. Open Developer Tools > Network.

    This will give you an overview of the network calls in the JavaScript console:

  3. Select XHR to filter on the Ajax calls.
  4. Execute the API call.

    Example

    You want to perform the call asset.get_by_url(url) on an asset with this URL: cloudflow://PP_FILE_STORE/notes.pdf.

    In the JavaScript console the call is the following: api.asset.get_by_url("cloudflow://PP_FILE_STORE/notes.pdf");

  5. Open the request in the network panel to see the details.
    • In the General section, you can see that the request was sent by a POST call to http://localhost:9090/portal.cgi.
    • In the Form Data section, you can see the submitted data. Make sure that you show the source version by clicking the view source button. The following data was sent:

      {"method":"asset.get_by_url","url":"cloudflow://PP_FILE_STORE/notes.pdf"}

      .
  6. Now all the information needed is available to perform the call with cURL:
    curl 'http://localhost:9090/portal.cgi' 
--data  '{"method":"asset.get_by_url","url":"cloudflow://PP_FILE_STORE/notes.pdf"}'

2. Pass the Authentication Information

However, when you do this you will get following error:

{
    "error_code":"no_permission",
    "error":"You don't have the correct permissions for the operation 'asset.get_by_url' !"
}
The reason for this is that browser cookies are not sent. Therefore you are not authenticated and the request returns an error.
Note: Sending the browser cookies will help in this case but it is not convenient.

In this case, the best way to authenticate is using the session field of the method request. When this field contains a valid session key, it will use this as authentication information. All calls support this extra field.

To do this, follow these steps:
  1. Create a session key with the following API call:

    api.auth.create_session(user_name, session).

    On the JavaScript console this would be:

    api.auth.create_session('admin');

  2. You receive the following response:

    {session: "56e172b93d5700000000009c0AA139F5D392075872DA1872949739EF1473716357"}

  3. Add the session key to the previous cURL call:
    {
    "method":"asset.get_by_url",
    "url":"cloudflow://PP_FILE_STORE/notes.pdf",
    "session": "56e172b93d5700000000009c0AA139F5D392075872DA1872949739EF1473716357"
}
  4. You receive the asset record:
    {
    "_id":"56e1819b44570000000001d7",
    "url":"PP_FILE_STORE/notes.pdf",
    "sub":"",
    "cloudflow": {
      "file":"cloudflow://PP_FILE_STORE/notes.pdf",
      "enclosing_folder":"cloudflow://PP_FILE_STORE/",
      "part":"cloudflow://PP_FILE_STORE/notes.pdf"
   },
   "file_name":"notes.pdf",
   "file_extension":".pdf",
   "document_name":"notes",
   "path":["PP_FILE_STORE"],
   "filetype":"application/pdf",
   "modtime":1457517078,
   "file_size":3639539,
   ...