In certain circumstances you may find yourself needing to use a raw cURL request to interact with our Management API. If that’s the case, you can use the examples in this article to help you out. Take into account that we strongly recommend using our native CraftAR-PHP and CraftAR-Python libraries to interact with our Management API instead of using cURL.
The scenarios for which we’ll be showing examples are:
- Create a Cloud Collection
- Create an On-Device Collection
- Create an IR (Image Recognition) Item
- Create an AR (Augmented Reality) Item
- Create an AR (Augmented Reality) Item with Custom Contents
- Create an Image for an Item
- Associate an Application ID to a Collection
- Obtain SDK Version Resource URI to create an On-Device Bundle
- Create an On-Device Bundle
- Regenerate an On-Device Bundle
- Obtain Collections for an Application ID
You need Python and the command line tool jq to run these examples. A full script with all the examples can be found here. The code for each example is written in Bash script and can be executed from your command line or saved in a Bash script file separately and executed as long as you include the utility methods from the full script. They each assume that there is an environment variable available called APIKEY which has the value of your account’s API Key that you can get here after logging in with your account.
Create a Cloud Collection
This example creates a Cloud Collection called “My Collection”.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
collection_name="My Collection"
echo "Creating a cloud Collection named $collection_name"
echo "--------------------------------------------------"
echo $'\n'
# encode the data required for collection creation in json
data='{"name":"'"$collection_name"'"}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/collection/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# later we'll use this to create an item in this collection
collection_resource_uri=$(get_json_field "resource_uri" "$body")
# echo to stdout the coammand executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Create an On-Device Collection
This example creates an On-Device Collection called “My Collection” by submitting the “offline” parameter set to “true”
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
|
collection_name="My On-Device Collection"
echo "Creating an On-Device Collection named $collection_name"
echo "--------------------------------------------------"
echo $'\n'
# encode the data required for collection creation in json.
# Note the 'offline' parameter to mark this collection as On-Device
data='{"name":"'"$collection_name"'", "offline": true}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/collection/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# later we'll use this to create an item in this collection
collection_resource_uri=$(get_json_field "resource_uri" "$body")
# echo to stdout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Create an IR (Image Recognition) Item
This example creates an Image Recognition Item called “My Item” in the Collection we created previously.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
item_name="My Item"
echo "Creating a Image Recognition (IR) Item named $item_name"
echo "---------------------------------"
echo $'\n'
# encode the data required for item creation in json
data='{"name":"'"$item_name"'", "collection": "'"$collection_resource_uri"'"}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/item/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# later we'll use this to create an image in this item
item_resource_uri=$(get_json_field "resource_uri" "$body")
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Create an AR (Augmented Reality) Item
This example creates an Augmented Reality Item called “My Item” in the Collection we created previously.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
|
item_name="My Item"
echo "Creating an Augmented Reallity (AR) Item named $item_name"
echo "---------------------------------"
echo $'\n'
# Note the 'trackable' parameter to mark this
# item as an Augmented Reality Item. Also have in mind that the scenes of AR are described in a json
# in the content field. Please check the format or use an existing scene as a template.
data='{"name":"'"$item_name"'", "collection": "'"$collection_resource_uri"'", "trackable": true}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/item/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# later we'll use this to create an image in this item
item_resource_uri=$(get_json_field "resource_uri" "$body")
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Create an AR (Augmented Reality) Item with Custom Contents
This example creates an Augmented Reality Item called “My Custom Content Item” in the Collection we created previously and specifying the JSON content which describes the scene for the Augmented Reality. In this example we’re adding an image content and a video content which includes a transparency mask. Read this article to learn how to describe contents programmatically in our JSON format. To know more about how we support videos with transparency in the CraftAR Service and in the SDKs, see how to add videos with transparency to Augmented Reality with CraftAR .
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
|
item_name="My Custom Contents Item"
echo "Creating an Augmented Reallity (AR) Item with custom content named $item_name"
echo "---------------------------------"
echo $'\n'
# Note the 'trackable' parameter to mark this
# item as an Augmented Reality Item.
data='{"name":"'"$item_name"'", "collection": "'"$collection_resource_uri"'", "trackable": true, "content": {
"version": 2,
"contents_v2": [
{
"id":"this image content id",
"type":"image",
"image_url":"http://url_to_image",
"scale": [1,1,1],
"translation": [0, 10, 0]
},
{
"id":"this video ID",
"type": "video",
"video_url": "http://url_to_mp4_file",
"transparency_mask": true,
"translation": [0, -10, 0]
}
]}
}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/item/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# later we'll use this to create an image in this item
item_resource_uri=$(get_json_field "resource_uri" "$body")
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Create an Image for an Item
This example creates an image on CraftAR from the file called myimage.jpg in the directory where the script is run. The image is associated to the Item we created in the previous examples.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
filename="myimage.jpg"
echo "Creating an Image using file $filename"
echo "--------------------------------------"
echo $'\n'
# curl command.
# Note that we are not using application/json content-type.
# images must be created using multipart/form-data encoding
cmd="curl -si -X POST '$HOST/api/v0/image/?api_key=$APIKEY' -F 'item=$item_resource_uri' -F 'file=@$filename'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Associate an Application ID to a Collection
This example associates an AppID to an existing collection. In this example we are using the previous On-Device Collection created, but it would also work with any Cloud Collection.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
|
appid_name="com.testing.mapi"
appid_description="My AppID"
echo "Associate the Application ID $appid_name to collection $collection_name"
echo "---------------------------------"
echo $'\n'
# requried parameters
data='{"name":"'"$appid_name"'", "collection": "'"$collection_resource_uri"'"}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/app/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# later we'll use this to create an On-Device Bundle
appid_resource_uri=$(get_json_field "resource_uri" "$body")
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Obtain SDK Version Resource URI to create an On-Device Bundle
This example retrieves the Resource URI for a given SDK Version to be used to create an On-Device Bundle.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
# sdk version parameters
sdk_version="4"
sdk_name="ARSDK"
echo "Obtain SDK version"
echo "---------------------------------"
echo $'\n'
# note the extra GET parameters sdk_version and sdk_name for filtering SDK Versions
cmd="curl -si -H 'Content-Type: application/json' '$HOST/api/v0/version/?api_key=$APIKEY&sdk_version=$sdk_version&sdk_name=$sdk_name'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# later we'll use this to create an On-Device Bundle
version_resource_uri=$(echo $body | jq '.objects | .[0] | .resource_uri')
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Create an On-Device Bundle
This example creates an On-Device Bundle for an existing collection and associated AppID.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
echo "Create Collection bundle for $appid_name in collection $collection_name"
echo "---------------------------------"
echo $'\n'
data='{"app":"'"$appid_resource_uri"'", "collection": "'"$collection_resource_uri"'", "version": '"$version_resource_uri"'}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/collectionbundle/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
echo "If you haven't purchased the Augmented Reality SDK plan add-on this call will probably fail"
echo $'\n'
|
Regenerate an On-Device Bundle
This example forces a regeneration of an existing On-Device Bundle by using the same call as Create. You’ll usually want to trigger regeneration of a Bundle when you’ve updated any of the Items in the Collection to which the Bundle is associated.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
# Just use the same call as create
echo "Regenerate Collection bundle for $dev_appid in collection $collection_name"
echo "---------------------------------"
echo $'\n'
data='{"app":'"$appid_resource_uri"', "collection": "'"$collection_resource_uri"'", "version": '"$version_resource_uri"'}'
#curl command
cmd="curl -si -X POST -H 'Content-Type: application/json' '$HOST/api/v0/collectionbundle/?api_key=$APIKEY' -d '$data'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|
Obtain Collections for an Application ID
This example retrieves the list of collections for an AppID on your account and some additional data for that AppID.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
# sdk version parameters
dev_appid="com.catchoom.test"
echo "Obtain the development Application ID $dev_appid"
echo "---------------------------------"
echo $'\n'
cmd="curl -si -H 'Content-Type: application/json' '$HOST/api/v0/app/?api_key=$APIKEY&name=$dev_appid'"
#eval command
response=$(eval $cmd)
#parse results
headers=$(get_headers $response)
body=$(get_body $response)
# obtain the appid resource uri
appid_resource_uri=$(echo $body | jq '.objects | .[0] | .resource_uri')
# echo to stout the command executed and the response from the server
echo "CURL COMMAND:"
echo $cmd; echo $'\n'
echo "RESPONSE FROM SERVER:"
echo "$headers"; echo $body | python -m json.tool
echo $'\n'
|