Specify References
POST
{urn}/references
Specifies the location of the files referenced by the specified source design.
If a source design contains references to other files, you must set checkReferences
to true
, when you call Create Translation Job. The Model Derivative service will then use the details you specify in this operation to locate and download the referenced files.
Resource Information
Method and URI | POST https://developer.api.autodesk.com/modelderivative/v2/designdata/{urn}/references |
Method and URI (EMEA) | POST https://developer.api.autodesk.com/modelderivative/v2/regions/eu/designdata/{urn}/references |
Authentication Context | user context optional |
Required OAuth Scopes | data:read and (data:write or data:create ) |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via
POST /authenticate/v2/token |
Content-Type* string | Must be application/json |
region enum: string | Specifies where the OSS bucket containing the referenced files are stored. Possible values are:
Note:
|
* Required
Request
URI Parameters
urn string | The URL safe Base64 encoded URN of the source design. |
Request
Body Structure
Expand all
urn object | The URN of the top level component of the design. Mandatory if the Base64 encoded urn in the request URL is a logical URN. |
region string | (DEPRECATED) Region to store reference information. Possible values: US , EMEA . By default, it is set to US .
Note: This attribute is replaced by the |
filename string | The file name of the top level component. By default, it is set to “” and the file will be download with its urn . |
references* array:object | An array of objects, where each object represents a referenced file. |
urn* string | The URN of the referenced file. |
relativePath string | The path to the referenced file, relative to the top level component. By default, it is set to “”, which means that the referenced file and top level component are in the same folder. |
filename string | The file name of the referenced file. By default, it is set to “” and the referenced file will be downloaded with its urn and relativePath . |
metadata object | An object to hold custom metadata. |
* object | A dictionary object containing custom key value pairs. |
* Required
Response
HTTP Status Code Summary
200 OK | Success. |
400 BAD REQUEST | Invalid request. E.g., the input URN format is invalid. |
401 UNAUTHORIZED | Invalid authorization header. |
403 FORBIDDEN | Access denied regardless of authorization status. |
404 NOT FOUND | Endpoint does not exist. |
406 NOT ACCEPTABLE | Unacceptable references specified. This may occur if one or more referenced files are stored in a different region than the source design. |
500 INTERNAL SERVICE ERROR | Unexpected service interruption. |
Response
HTTP Headers
x-ads-app-identifier string | The service identifier. Comprised of the service name, version, and environment. |
x-ads-duration string | The request duration in milliseconds. |
x-ads-startup-time string | The service startup time with data format EEE MMM dd HH:mm:ss Z yyyy . |
Response
Body Structure (200/201)
result string | The result of the operation. Always success . |
urn string | The URN of the top level component. |
Response
Body Structure (400)
diagnostics string | reason for failure |
Example 1
Successful creation of references for a source file (200)
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJjbGllbnRfaWQiOiJwb2VieTZHblBiYXRjdjF6QXRrNVQ1bjR4NWduNnM4QSIsImV4cCI6MTUwNDI1MDQ2Niwic2NvcGUiOlsiZGF0YTpyZWFkIiwiZGF0YTp3cml0ZSIsImRhdGE6Y3JlYXRlIl0sImF1ZCI6Imh0dHBzOi8vYXV0b2Rlc2suY29tL2F1ZC9qd3RleHA2MCIsImp0aSI6IjdIbmYwQVNXaEVMS1hBWE9nNlY0MXNuR0IxbWRBalpiODZta3lYQTE5VDVsMm5LcTFTbzUzVm00dUlRY0I4bUUifQ.oKhJktcL-yWud9diJujWoAZTqNlXdBlso-xSLPFNMsI' \
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LmlhbQ/references' \
-d
'{
"urn": "urn:adsk.objects:os.object:modelderivative/A5.iam",
"filename": "A5.iam",
"references": [{
"urn": "urn:adsk.objects:os.object:modelderivative/01.ipt",
"relativePath": "refs/01.ipt",
"filename": "01.ipt",
"references": [{
"urn": "urn:adsk.objects:os.object:modelderivative/011.ipt",
"relativePath": "refs/subfolder/011.ipt"
}]
},
{
"urn": "urn:adsk.objects:os.object:modelderivative/02.ipt",
"relativePath": "x-refs/02.ipt",
"filename": "02.ipt",
"metadata": {
"myField1": "Some Data1",
"myField2": "Some Data2",
"myField3": "Some Data3"
}
}]
}'
Show More
Response
Status Code: 200 OK
Access-Control-Allow-Credentials:true
Access-Control-Allow-Origin:*
Connection: keep-alive
Content-Length:20
Content-Type:application/json;charset=utf-8
Date: Fri, 01 Sep 2017 05:57:34 GMT
x-ads-app-identifier:platform-viewing-2017.07.02.32.cf55416-production
x-ads-duration:112 ms
x-ads-startup-time:Wed Aug 30 03:20:17 UTC 2017
'{
"result": "success"
}'
Show More
Example 2
This example illustrates what happens when the source design and the referenced files are not stored in the same region. The system returns an HTTP status (406) error for this request.
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJjbGllbnRfaWQiOiJwb2VieTZHblBiYXRjdjF6QXRrNVQ1bjR4NWduNnM4QSIsImV4cCI6MTUwNDI1MDQ2Niwic2NvcGUiOlsiZGF0YTpyZWFkIiwiZGF0YTp3cml0ZSIsImRhdGE6Y3JlYXRlIl0sImF1ZCI6Imh0dHBzOi8vYXV0b2Rlc2suY29tL2F1ZC9qd3RleHA2MCIsImp0aSI6IjdIbmYwQVNXaEVMS1hBWE9nNlY0MXNuR0IxbWRBalpiODZta3lYQTE5VDVsMm5LcTFTbzUzVm00dUlRY0I4bUUifQ.oKhJktcL-yWud9diJujWoAZTqNlXdBlso-xSLPFNMsI' \
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LmlhbQ/references' \
-d
'{
"urn": "urn:adsk.objects:os.object:modelderivative/A5.iam",
"filename": "A5.iam",
"references": [{
"urn": "urn:adsk.objects:os.object:modelderivative/01.ipt",
"relativePath": "refs/01.ipt",
"filename": "01.ipt",
"references": [{
"urn": "urn:adsk.objects:os.object:modelderivative/011.ipt",
"relativePath": "refs/subfolder/011.ipt"
}]
},
{
"urn": "urn:adsk.objects:os.object:modelderivative/02.ipt",
"relativePath": "x-refs/02.ipt",
"filename": "02.ipt",
"metadata": {
"myField1": "Some Data1",
"myField2": "Some Data2",
"myField3": "Some Data3"
}
}]
}'
Show More
Response
Status Code: 406 Not Acceptable
Access-Control-Allow-Credentials:true
Access-Control-Allow-Origin:*
Connection: close
Content-Length:144
Content-Type:application/json;charset=utf-8
Date: Fri, 01 Sep 2017 06:00:42 GMT
x-ads-app-identifier:platform-viewing-2017.07.02.32.cf55416-production
x-ads-duration:34 ms
x-ads-startup-time:Wed Aug 30 03:20:17 UTC 2017
'{
"diagnostic": "Can not register the same design on different regions, you should delete old registration for register it to another region."
}'
Show More