AMAGE REST API Interface - Attachments

Introduction/Context

Context for downloading attachments in the AMAGE system, which should be extended with the appropriate method in the query.

rest/amage/v1/attachments

Data structures

Structures and data types used in queries and responses.

Type of objects on which we perform operations with attachments

object-type - the type of object for which we want to download attachments. Possible values:
- folder - folder in the structure
- asset - resource
- element-type - type of elements
- work-order - work order

List of main folders

Displays a list of root directories in the AMAGE system.

Method: GET
Path: /list/folders
Generates: application/json
Requires: text/plain, application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Returns a list of all root folders in the AMAGE system.

Query

/rest/amage/v1/attachments/list/folders/

Response

[
  {"uuid":"f6b0430e-e441-4927-adaf-bbaf0099aa2b","name":"Test 1"},
  {"uuid":"a7bcd271-2699-4aea-9aee-e637da12d38a","name":"Test 2"},
  {"uuid":"db01b47c-68aa-4c12-8786-9992201d8ea9","name":"Test 3"}
]

List of folders

Displays a list of directories in a given parent directory.

Method: GET
Path: /list/folders/{parent-uuid}
Generates: application/json
Requires: text/plain, application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Returns a list of all folders in the given parent directory. If the parent directory does not exist, returns an empty list.

Query

/rest/amage/v1/attachments/list/folders/f6b0430e-e441-4927-adaf-bbaf0099aa2b

Response

[{"uuid":"14f80a0d-b7ae-4ff7-99f6-d5a60a73400d","name":"test 1-1"},{"uuid":"75c90ac5-6ec8-448f-a345-1be0407548b1","name" :"test 1-2"}]

Returns a list of attachment categories

Method: GET
Path: /list/attachment-categories
Generates: application/json
Requires: text/plain, application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Returns a list of attachment categories available in the system. Returns the category name and category UUID.

Query

/rest/amage/v1/attachments/list/attachment-categories

Response

[
  {
    "uuid":"8982a7bb-916e-469a-bce0-1194d7e26844",
    "name":"CATEGORY 1"
  },
  {
    "uuid":"ddb7a579-9a4e-42a0-8384-ce95be56f16c",
    "name":"CATEGORY 2"
  }
]

List of attachments for objects

Returns a list of attachments assigned to an object.

Method: GET
Path: list/by-object/{object-type}/{uuid}
Generates: application/json
Requires: text/plain, application/json
Authorization: API signature (device-uuid, api-key, api-sign)

In the query object-type is the type of object for which we want to retrieve attachments. Possible values are given in the "Data structures" section. UUID is the identifier of the object for which we want to retrieve attachments. In the response we will get a list of attachments assigned to the object. Each attachment contains UUID, file name, MD5 hash and file size. If the object is not found, an empty list is returned.

Query

/rest/amage/v1/attachments/list/by-object/folder/f6b0430e-e441-4927-adaf-bbaf0099aa2b

Response

[
  {
    "uuid":"be80c1f3-b2e7-4617-9767-d0c516e836d4",
    "fileName":"file1.jpg",
    "hash":"14DAED0F5B6A3B1147D75458DF910BAC",
    "fileSize":3710094
  },
  {
    "uuid":"079e76d6-c360-4c76-b6d5-cb98d6132f91",
    "fileName":"file2.jpg",
    "hash":"275635D68FCB03543DDF3695C9C43746",
    "fileSize":295349
  }
]

Downloading an attachment after providing the UUID

To download an attachment from the AMAGE system, perform an HTTP GET request to the appropriate URL address. In the query, you must provide the UUID of the attachment you want to download. In response, we will receive a binary file that should be saved on the local disk.

Method: GET
Path: get/by-uuid/{uuid}
Generates: application/octet-stream
Requires: text/plain, application/json
Authorization: API signature (device-uuid, api-key, api-sign)

UUID is the identifier of the attachment we want to download.

After executing the query, we will receive a binary file in response, which should be saved on the local disk. Python example code below.

Query

/rest/amage/v1/attachments/get/by-uuid/e900899f-8899-414c-9570-6bb3ed69cf9d

Response

<binary file>.

Downloading the attachment after providing the attachment’s MD5 HASH

Downloading an attachment from the AMAGE system after providing its MD5 hash. In the query, you must provide the MD5 hash of the attachment you want to download. In response, you will receive a binary file that should be saved to your local disk.

Method: GET
Path: /get/by-hash/{hash}
Generates: application/octet-stream
Requires: text/plain, application/json
Authorization: API signature (device-uuid, api-key, api-sign)

HASH is the MD5 hash of the attachment we want to download.

Query

/rest/amage/v1/attachments/get/by-hash/275635D68FCB03543DDF3695C9C43746

Response

<binary file>.

Uploading a file to an object

It allows you to upload a file to an object in the AMAGE system. In the query, you must provide the type of object to which you want to upload the file, the UUID of the object and the file you want to upload. In response, you will receive the UUID of the attachment, the MD5 hash and information about the success of the operation.

Method: PUT
Path: /put/to-object/{object-type}/{uuid}
Generates: application/json
Requires: multipart/form-data
Authorization: API signature (device-uuid, api-key, api-sign)

The following parameters must be provided in the query:

filename - file name as URL parameter
public - whether the file should be public (true/false) as a URL parameter
category-uuid - UUID of the attachment category
file (Multipart) - the file that we want to upload to the object in Multipart format

Query

/rest/amage/v1/attachments/put/to-object/element-type/1c4066e6-cdd6-4903-803a-b6bffe689527?filename=item.png&public=true&category-uuid=feed29b6-d093-42af-8de6-7bda99c37a3b

<binary file>.

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "hash":"E05B9766B5108FA37BA554C7FB8B9F56",
    "success":true,
    "errorCode":0,
    "message":""
}

Incorrect answer (incorrectly stated UUID of attachment category)

Response code: BAD_REQUEST (400)

Response

{
    "uuid": null,
    "hash": "",
    "success": false,
    "errorCode": 404,
    "message":"Attachment Category not found"
}

Attaching an existing file to another object

It allows you to attach an existing file in the AMAGE system to another object. In the query, you must provide the type of object to which you want to upload the file, the UUID of the object and the UUID of the attachment that you will be attaching to the new object. In response, you will receive the UUID of the new attachment, the MD5 hash and information about the success of the operation.

Method: POST
Path: /join/to-object-by-uuid/{object-type}/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

The following parameters must be provided in the query:

attachment-uuid - UUID of the attachment that we want to attach to the new object
filename - file name as URL parameter
public - whether the file should be public (true/false) as a URL parameter
category-uuid - UUID of the attachment category

Query

/rest/amage/v1/attachments/join/to-object-by-uuid/element-type/1c4066e6-cdd6-4903-803a-b6bffe689527?filename=item.png&public=true&category-uuid=feed29b6-d093-42af-8de6 -7bda99c37a3b&attachment-uuid=455d6797-625f-467b-9640-cb9ee5d9d449

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "hash":"E05B9766B5108FA37BA554C7FB8B9F56",
    "success":true,
    "errorCode":0,
    "message":""
}

Attachment update

We update the parameters of an existing attachment. We provide the attachment UUID and new parameters such as file name, attachment category UUID and public/private status. The system updates the information.

Method: POST
Path: /update/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

The following parameters must be provided in the query:

uuid - UUID of the attachment we are modifying
filename - file name as URL parameter
public - whether the file should be public (true/false) as a URL parameter
category-uuid - UUID of the attachment category

Query

/rest/amage/v1/attachments/update/1c4066e6-cdd6-4903-803a-b6bffe689527?filename=newitem.png&public=false&category-uuid=feed29b6-d093-42af-8de6-7bda99c37a3b

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "hash":"E05B9766B5108FA37BA554C7FB8B9F56",
    "success":true,
    "errorCode":0,
    "message":""
}

Removal of attachment

We remove the attachment. We provide the UUID of the attachment that we want to remove. The system removes the attachment from the system. The system checks the attachment’s connection to other objects and if the attachment is connected to other objects that are not its source object (e.g. resource documentation), it does not allow the attachment to be removed.

Method: DELETE
Path: /delete/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

The following parameters must be provided in the query:

uuid - UUID of the attachment we are modifying

Query

/rest/amage/v1/attachments/delete/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "hash":"E05B9766B5108FA37BA554C7FB8B9F56",
    "success":true,
    "errorCode":0,
    "message":""
}

Example of downloading an attachment in Python

import binascii
import requests
import hashlib

PARAM_SEPARATOR = ";"

def calc_api_sign(path, api_secret):
    message_digest = hashlib.sha256()
    message_digest.update(bytearray.fromhex(api_secret))
    message_digest.update(PARAM_SEPARATOR.encode('utf-8'))
    message_digest.update(path.encode('utf-8'))
    return message_digest.digest()

def download_file(url, headers, local_filename):
    with requests.get(url, headers=headers, stream=True) as r:
        r.raise_for_status()
        with open(local_filename, 'wb') as f:
            print("received return code: {0}".format(r.status_code))
            for chunk in r.iter_content(chunk_size=8192):
                f.write(chunk)
    return local_filename


# define local filename
local_filename = r"/home/user/filename.pdf"
attachment_uuid = "67dc0c69-b1f3-437e-8d9b-f4722bffe2ab"
request_path = 'attachments/get/by-uuid/' + attachment_uuid

# define headers' values
device_uuid = "75d2b25d-4698-48b9-bb62-7569ffb763fc"
api_key = "690f8eaecc5743bfcd82121a15abb5b1"
api_secret = "f4affb2db24b2b0903ad89ceeb622ece"
api_sign = binascii.hexlify(calc_api_sign(request_path, api_secret)).decode()

# define url
url = "https://app.amage24.com/999-99/rest/amage/v1/" + request_path

# define headers
headers = {
    "Content-Type": "text/plain",
    "Accept": "application/octet-stream",
    "amage-device-uuid": device_uuid,
    "amage-api-key": api_key,
    "amage-api-sign": api_sign
}

# download file
download_file(url, headers, local_filename)

Example of sending a file to a server using Python code

#!/usr/bin/python3

import binascii
import hashlib

import requests

PARAM_SEPARATOR = ";"


def calc_api_sign(path, api_secret):
    message_digest = hashlib.sha256()
    message_digest.update(bytearray.fromhex(api_secret))
    message_digest.update(PARAM_SEPARATOR.encode('utf-8'))
    message_digest.update(path.encode('utf-8'))
    return message_digest.digest()


def put_file(server_url, headers, filename, path):
    if 'Content-Type' in headers:
        del headers['Content-Type']

    print(server_url + path)
    with open(filename, 'rb') as f:
        files = {'file': (filename, f)}
        response = requests.put(server_url + path, headers=headers, files=files)
        print("received return code: {0}".format(response.status_code))
        print("received data: {0}".format(response.text))


def get_header(path, content_type, accept):
    headers = {
        "Content-Type": content_type,
        "Accept": accept,
        "amage-device-uuid": device_uuid,
        "amage-api-key": api_key,
        "amage-api-sign": binascii.hexlify(calc_api_sign(path, api_secret)).decode()
    }
    return headers

local_filename = "item.png"
asset_uuid = "bb424ebd-5bba-49aa-8503-2edc31f5fc05"

server_url = "https://amage-server-example.com/999-99/rest/amage/v1/"

device_uuid = "75d2b25d-4698-48b9-ca23-7569343323fc"
api_key = "690f8eaecc574343543521a15abb5b1"
api_secret = "f4affb2d234246903ad89ceeb622ece"

# adds the file to the resource
put_file(server_url, get_header("attachments/put/to-object/asset/" + asset_uuuid, "multipart/form-data", "application/json"), local_filename
"attachments/put/to-object/asset/" + asset_uuid + "?filename=" + local_filename + "&public=true")

AMAGE REST API Interface - Attachments

Introduction/Context

Data structures

Type of objects on which we perform operations with attachments

List of main folders

List of folders

Attachment Category List

List of attachments for objects

Downloading an attachment after providing the UUID

Downloading the attachment after providing the attachment’s MD5 HASH

Uploading a file to an object

Attaching an existing file to another object

Attachment update

Removal of attachment

Example of downloading an attachment in Python

Example of sending a file to a server using Python code