New session with "curl"

To perform these steps we provide a REST interface. The following description is a reference example on how to use this REST interface. We showcase the procedure with the curl command line application (with most Linux users will recognize) The curl executable can be installed via this link on Windows. For Linux use the package manager of your distribution to install it. The example with the two applications should give enough insight in the process to adapt it to your favorite REST tool or programming language of choice. All major programming languages provide the possibility to communicate with a REST API.

Our target group are Windows users, so the steps below are using Windows-style paths. Otherwise the commands do not differ on Linux, though.

Step 1 - Upload file(s)

In this example we are going to create a session with two files, a BIM model (Nygade_Scan1005-1006.ifc) and a corresponding point cloud scan (Nygade_Scan1005-1006.e57), which are both located in the C:\tmp folder. The corresponding curl command line to upload the files is:

curl -F file=@C:\tmp\Nygade_Scan1005-1006.e57 -F file=@C:\tmp\Nygade_Scan1005-1006.ifc http://localhost/api/v0.7/sessions/uploads/upload

A successful upload returns the following output:

{
  "files": [
    {
      "path": "/duraark-storage/uploads/upload-68b7dce7-060f-4303-acf0-198845996681/Nygade_Scan1005-1006.e57",
      "type": "e57",
      "size": 54495,
      "atime": "2015-10-21T11:44:42.534Z",
      "mtime": "2015-10-21T11:44:42.534Z",
      "ctime": "2015-10-21T11:44:42.534Z"
    },
    {
      "path": "/duraark-storage/uploads/upload-68b7dce7-060f-4303-acf0-198845996681/Nygade_Scan1005-1006.ifc",
      "type": "ifc-spf",
      "size": 54495,
      "atime": "2015-10-21T11:44:42.534Z",
      "mtime": "2015-10-21T11:44:42.534Z",
      "ctime": "2015-10-21T11:44:42.534Z"
    }
  ]
}

The output indicates that two files were uploaded to a certain path each. Metadata about the file like the size and the type are also returned.

If the upload command does not work you can get more information on what is going on when using the -i -v flag for the curl command like so:

curl -i -v -F file=@C:\tmp\Nygade_Scan1005-1006.e57 -F file=@C:\tmp\Nygade_Scan1005-1006.ifc http://localhost/api/v0.7/sessions/uploads/upload

The output of the command then includes more information useful for debugging.

Step 2 - Create a new session

To add the files to the WorkbenchUI it is necessary to create a session that holds the uploaded files. To create a new session use this command:

curl -H "Content-Type: application/json" -X POST -d '{"label":"My Session","address":"My demo address","description":"My first API test session!"}' http://localhost/api/v0.7/sessions/sessions

the -d parameter is followed by a JSON string that encodes the label, address and description of the new session. Those three parameters are mandatory. The success response of the command looks like this:

{
  "state": "new",
  "label": "My Session",
  "address": "My demo address",
  "description": "My first API test session!",
  "physicalAssets": [
    {
      "label": "My Session",
      "buildm": {
        "@id": "http://data.duraark.eu/physicalasset_c2db7ad5-8fcc-4cd4-9ed2-b18432b65d99",
        "@type": "http://data.duraark.eu/vocab/buildm/PhysicalAsset",
        "http://data.duraark.eu/vocab/buildm/name": [
          {
            "@value": "My Session"
          }
        ]
      }
    }
  ],
  "digitalObjects": [],
  "config": {
    "sda": {
      "topics": [
        "Haus 30 (general context)",
        "Haus 30 (political context)"
      ]
    },
    "geometricenrichment": {
      "tools": [
        "IFC Reconstruction"
      ]
    }
  },
  "sessionFolder": "/duraark-storage/sessions/duraark-session-51513c0c-0051-4f71-9f66-883d28cf2d28",
  "files": [],
  "createdAt": "2015-10-21T11:55:38.851Z",
  "updatedAt": "2015-10-21T11:55:38.851Z",
  "id": 4
}

The output is again a JSON string holding information on the newly created session. The files array is currently empty, but we will change that in the next steps.

Open the URL http://localhost/preingest in a browser to see the newly create session showing up.

Step 3 - Associate the uploaded files with the created session

As a last step we have to associate the uploaded files with the session. To do that we use information from the first two steps and create the following curl command with it:

curl -H "Content-Type: application/json" -X POST -d '{"sessionId": 4, "files":[{"path":"/duraark-storage/uploads/upload-68b7dce7-060f-4303-acf0-198845996681/Nygade_Scan1005-1006.e57"}, {"path":"/duraark-storage/uploads/upload-68b7dce7-060f-4303-acf0-198845996681/Nygade_Scan1005-1006.ifc"}]}' http://localhost/api/v0.7/sessions/sessions/addFilesToSession

The sessionId is the id field in the JSON output from Step 1. The files array is assembled with the path fields from the JSON output in Step 2.

Open the URL http://localhost/preingest in a browser and click on the session to start working with the uploaded files.