API Flow Tutorial

This tutorial describes the complete set of actions and API method calls that need to be executed to perform a repair operation on a 3d model file.
Note: the repair operation is just an example, you can substitute it by any other operation or a chain of those.

  1. First you need to obtain an Authorization Token for your user account. For a detailed description check this link: https://api.cloud.materialise.com/help/authorization

    1. Perform a POST request on the /Token endpoint, substituting the values in bold with your credentials:

      application/x-www-form-urlencoded

      
      POST https://api.cloud.materialise.com/Token HTTP/1.1
      Authorization: Basic dGVzdF91c2VyOnRlc3Rfc2VjcmV0
      Content-Type: application/x-www-form-urlencoded
      Host: api.cloud.materialise.com
      
      grant_type=password&username=test@test.com&password=my_password
                      
      

      While the body of the request: the username and password are self-explanatory, the first string in the authorization header can be obtained by encoding to Base 64 the string with the pair API Client Id and API Client Secret separated by a colon. In this example the pair “test_user:test_secret” becomes dGVzdF91c2VyOnRlc3Rfc2VjcmV0.

    2. If all parts of the request are correct, you will receive a JSON response from the server with the Authorization Tokens, you need the “access_token” highlighted in bold:

      application/json

      
      HTTP/1.1 200 OK
      Cache-Control: no-cache
      Pragma: no-cache
      Content-Length: 851
      Content-Type: application/json;charset=UTF-8
      Expires: -1
      Date: Thu, 30 Jul 2015 09:05:54 GMT
      
      {"access_token":"Eye8dHrbdJGPkfOf0AyHEoR5mWoa-JJTjFt5XqGQL5s3wbG6ghks7QrcgFVH8tTwo7WlSRjOJBqm6ogqy49O_SB3FnjTCc1SS6pD4r3kYGh96O3u1kaWNBFvdVYJG3Aw89sOCGQOaB_zJsJGfXjYxpeNUVbVDvmGDEmmoCrpoyObz2kPHBpfIlCkQtDCew280HErrlqZz-EB6EygRb4AZ0Ri5ODT5jn8ZSDH5PlUPTtHVWZRmIODqABHPxDSAPWa5_-LD96BQxZhmYtNTc3GBSRifvxi29-_2J5E5yU1MCfHr9dytmQEBNMXf3ckLalmbD34wmYgNPr8O_pM__LPHe9ymy03RYeNXDCi2uvUhRtFAMfj0-OR8_O-Zuxf1aRUz3zqRCgayqymuWduRwFHeouWoFmlK5BBGtCknBA6NDarZ0gimnEDld7o6AShZR2ZFzBnnMRXTFH1mu-Lfre1TW0BfUwpNFDo-49itELxXcgerGsok61yIsaxVKQ-uf5NWw0m29TnkZB5nSyxOtyJ_ZVKBoSbtMWbLNGAh0S6uJLSDZTwY2gqgxPAcxAFbyBSxhl1Fg",
      "token_type":"bearer",
      "expires_in":899,
      "refresh_token":"a5beac8430c64d81aa3282c9f19a183e",
      "userName":"25bbc91c-a4ac-4877-b5a0-0aad9deb34c0",
      "as:client_id":"apitest",
      ".issued":"Thu, 30 Jul 2015 09:05:49 GMT",
      ".expires":"Thu, 30 Jul 2015 09:20:49 GMT"}
      

      Also notice that the access token has an expiration time in seconds stored in the field “expires_in”. After the token has expired you can either request another one by following the steps described above or user Refresh tokens (out of scope of this article).

  2. With the Authorization Token at hand, you are ready to upload your 3d model file.

    1. Perform a multipart/form-data POST request on the /web-api/operation/file endpoint:

      multipart/form-data

      
      POST https://api.cloud.materialise.com/web-api/operation/file  HTTP/1.1
      Authorization: Bearer djxmeOuuVxPR1LbyopkMlWtpL6GcxckYN-74Sn9wREke70X9G6osLFt8-1vFzJZJ9ZaMe6ytioA7U2mq7r9qOEs9jg8R7lxRoWf-HRhNPIgoUdf6EFO_tFyF4NdkkC9eins-zl-NxN4XXQLmPFE0Qpcb4mlNRTETeQ-aX38PasCsi2Ylvdqtl48HDNpf76kKbDaE83nq3DuA3cAqAbUMnMOUf2dC2dTX0VC2Bajs-q0FI7xiNgDN2fuaLpPMCRlMR_wGt68mrnrmm-55WFjYUxFGLlsrLJERHeftXeagPeMzCGht0DFxH4LzhEssfu4wPUoAiL0XcPfD1FTkbZpWZtSHtcLPQ8N4R-B1s5md_A1fMSrLoqhZKz9q2-CuBSsy6A7olziacje3bqX9ZpG1gB6wSsjD4Htlk7EM3tCSC86cLP_dJtPxH6bCRZdXgGuQADgYbETsMNBhQ5cZo-P8WBnUNzKaBMvgdSvzFu8v0z3Js1Yc2urks_3kUW1Mox5bqrCHTA
      Content-Length: 1268
      Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
      
      ---------------------------acebdf13572468
      Content-Disposition: form-data; filename="Plug.stl"
      Content-Type: application/vnd.ms-pki.stl
      
      { file-contents-here}
      ---------------------------acebdf13572468--
      
      

      Substitute the value in bold of the Authorization header with the Authorization Token from the first step of this tutorial.
      Content-Length is a required field and must be set to the total number of bytes of the whole request body, it will be used by the server to correctly determine the end of the content body.
      Content-Type header value should be set to multipart/form-data followed by a semicolon and the value of the boundary string which denotes the boundaries of the content in the body of the request.
      Inside the boundary string the filename value is required, as it will be used by the server to determine the format of the 3d model file.
      The placeholder {file-contents-here} marks the place where the file’s byte content should be put.

      NOTE: from this point on, the Authorization header will be omitted from the examples for simplicity’s sake, but it should be included with every request you make to our APIs.

    2. If the request was performed correctly, you should get a JSON response from the server with the Id of the file you’ve just uploaded to our server:

      application/json

      
      {
        "fileId": "2a598eb1-2427-4363-8d17-850b0b92e128",
        "creationDate": "2016-06-24T08:47:26.5854111+00:00",
        "fileUrl": "https://foo.com/sample-url-3"
      }
      
      
  3. To be able to perform operations on the 3d model file you’ve just uploaded in the previous step, you need to import the file into our system by calling the Import operation. The idea of the Import operation is to convert the file of an arbitrary supported 3d model format into our own proprietary format, optimized for performing various geometrical algorithms. Think of it as importing a 3d model of a 3rd party format into a CAD system or importing an .mp3 file into a DAW software project.

    1. To execute the Import operation, perform a POST request on the /web-api/operation/import endpoint, supplying the file Id obtained in the previous step in the JSON body of the request, as well as measurement units (if applicable to your file format):

      application/json

      
      POST https://api.cloud.materialise.com/web-api/operation/import  HTTP/1.1
      
      {
        "fileId": "2a598eb1-2427-4363-8d17-850b0b92e128",
        "measurementUnits": "mm",
        "callbackUrl": "https://foo.com/sample-url-3"
      }
      
      

      You can also supply a callback URL which will be called by our server once the operation is complete. The callback JSON has the following structure:

      application/json

      
      {
        "operationId": "9688e1c9-eff7-42b2-bae0-4ac6e1085985",
        "isSuccessful": "true"
      }
      
      
    2. If everything is correct you will get a JSON response from the server with the operation handle Id. Because the operation is asynchronous and might take some time to complete depending on the size and complexity of the model, you will need to wait for the operation to finish to get the actual results of the operation:

      application/json

      
      {
        "operationId": "9688e1c9-eff7-42b2-bae0-4ac6e1085985"
      }
      
      
    3. To know when an operation has finished and it’s time to get the results, you can either poll on the operation status endpoint or wait for a callback described in point a) of this section. To perform an operation status request, just execute a GET request on the /web-api/operation/{operationId}/status endpoint:

      application/json

      
      GET https://api.cloud.materialise.com/web-api/operation/9688e1c9-eff7-42b2-bae0-4ac6e1085985/status  HTTP/1.1
      
      

      You will get a JSON response where you are mainly interested in the field “isCompleted” which should quite obviously have the value “true”:

      application/json

      
      {
        "operationId": "9688e1c9-eff7-42b2-bae0-4ac6e1085985",
        "isCompleted": true,
        "isSuccessful": true
      }
      
      

      Keep calling the operation status endpoint with some intervals in between until the operation is completed.

    4. Once the operation is completed you can call the operation result endpoint to get the actual result of the operation. Perform a GET request on the /web-api/operation/{operationId}/import/result endpoint:

      application/json

      
      GET https://api.cloud.materialise.com/web-api/operation/9688e1c9-eff7-42b2-bae0-4ac6e1085985/import/result  HTTP/1.1
      
      

      You will get a JSON response:

      application/json

      
      {
        "operationId": "9688e1c9-eff7-42b2-bae0-4ac6e1085985",
        "resultId": "5742638e-96db-4170-a431-0719dc605998"
      }
      
      

      The result id handle is an identifier of the resulting entity, stored in our internal format. You can use the result id to perform operations on your model or call the Export API method to export the result to a common format (e.g. STL) and download the exported file.

  4. Now with your model successfully imported into our system, it’s time to execute the Repair operation on it.

    1. Perform a POST request on the /web-api/operation/repair endpoint, providing the id of your imported model (“resultId”) in the JSON body as “inputId” (as well as the callback URL, same as for the operation above):

      application/json

      
      POST https://api.cloud.materialise.com/web-api/operation/repair  HTTP/1.1
      
      {
        "inputId": "5742638e-96db-4170-a431-0719dc605998",
        "callbackUrl": "https://foo.com/sample-url-2"
      }
      
      

      You will get a JSON response with the Repair’s operation id:

      application/json

      
      {
        "operationId": "7f6630d6-aa27-451c-a998-9b2b6e9ebcc0"
      }
      
      
    2. Wait for the operation to finish (see previous section, the approach is the same).

    3. Once the Repair operation has finished, perform a GET request on the /web-api/operation/{operationId}/repair/result endpoint:

      application/json

      
      GET https://api.cloud.materialise.com/web-api/operation/7f6630d6-aa27-451c-a998-9b2b6e9ebcc0/repair/result  HTTP/1.1
      
      

      You will get a JSON response with the result identifier for your repaired model:

      application/json

      
      {
        "operationId": "7f6630d6-aa27-451c-a998-9b2b6e9ebcc0",
        "resultId": "53b05f94-f3aa-48b6-9763-64b26bea8f1f"
      }
      
      
  5. Now that the repair operation has finished successfully it’s time to download the results. To do that, you need to perform an Export operation:

    1. Execute a POST request on the Export operation endpoint /web-api/operation/export providing the result id of the previous operation as “inputId” and specifying which format to export to:

      application/json

      
      POST https://api.cloud.materialise.com/web-api/operation/export  HTTP/1.1
      
      {
        "inputId": "53b05f94-f3aa-48b6-9763-64b26bea8f1f",
        "exportToFormat": "stl",
        "callbackUrl": "https://foo.com/sample-url-2"
      }
      
      

      You will get a JSON response with the Repair’s operation id:

      application/json

      
      {
        "operationId": "dd3ca8b6-fe3a-4033-99f3-6c5bdb1fdc55"
      }
      
      
    2. Wait for the operation to finish.

    3. Once the Export operation has finished, perform a GET request on the /web-api/operation/{operationId}/export/result endpoint:

      application/json

      
      GET https://api.cloud.materialise.com/web-api/operation/dd3ca8b6-fe3a-4033-99f3-6c5bdb1fdc55/export/result  HTTP/1.1
      
      

      You will get a JSON response with the id of the exported file:

      application/json

      
      {
        "operationId": "dd3ca8b6-fe3a-4033-99f3-6c5bdb1fdc55",
        "fileId": "53b05f94-f3aa-48b6-9763-64b26bea8f1f"
      }
      
      
  6. The only thing left is to download the resulting file. You can do that by executing a GET request on the File Download endpoint /web-api/operation/file/{fileId}, providing the file id in the url:

    application/json

    
    GET https://api.cloud.materialise.com/web-api/operation/file/53b05f94-f3aa-48b6-9763-64b26bea8f1f  HTTP/1.1
    
    

    And that’s it! The Repair operation was used an example, you can perform any number of operations the same way as described in the tutorial by simply passing the result of an operation as input to the next operation. Just be sure to remember that to start operations on a file you need to call the Import operation on it, and to get the result as an STL file you need to call the Export endpoint to export the results into a known format. Happy coding!

Upload file

POST /web-api/operation/file

fileId

Import

POST /web-api/operation/import

operationId

Import operation status

GET /web-api/operation/{id}/status

operationId

Import operation result

GET /web-api/operation/{id}/import/result

resultId

Repair operation

POST /web-api/operation/repair

operationId

Repair operation status

GET /web-api/operation/{id}/status

operationId

Repair operation result

GET /web-api/operation/{id}/repair/result

resultId

Export

POST /web-api/operation/export

operationId

Export operation status

GET /web-api/operation/{id}/status

operationId

Export operation result

GET /web-api/operation/{id}/export/result

fileId

Download file

GET /web-api/operation/file/{id}