-
Notifications
You must be signed in to change notification settings - Fork 16
API Documentation
3DR API Reference The ADL 3D Repository exposes functions in two formats. XML and JSON. You can access models in the repository by calling functions with either of these formats. The API Key is a value assigned to you by the repository you are accessing. Use the web interface to create and manager your API keys. The value {api base url} is the base address of the service hosted by the repository. The address of the public API on the ADL main 3DR instance is 3dr.adlnet.gov/api/rest
The 3DR uses HTTP-Basic Authentication to authenticate users. The API should be configured to connect to the same membership database as the web front end - otherwise users with accounts on the website will not have accounts on the API, which could be very confusing. The API will challenge users to present credentials when the requested operation requires credentials greater than the default user’s credentials. The API by default is set to use AnonymousUser’s credentials when no WWW-Authenticate header is provided.
This function returns a list of pid’s and document titles that match the search terms. The datalink portion of the response contains the link to the metadata. The XML will be returned in the following format:
<ArrayOfSearchResult>
<SearchResult>
<PID>{pid}</PID>
<Title>{title}</Title>
<Datalink>{link}</Datalink>
</SearchResult>
</ArrayOfSearchResult>
The JSON will be returned in the following format:
[
{
PID: "{pid}",
Title: "{title}"
Datalink: "{link}"
}
]
Use JSONP to get the search terms. Use then when making cross domain ajax requests to an API instance.
Get an XML encoded metadata structure for the given pid
<Metadata>
<AnonymousDownloadAvailable>false or true</AnonymousDownloadAvailable>
<ArtistName>{the name of the artist}</ArtistName>
<AssetType>Model</AssetType>
<ConversionAvailable>true or false</ConversionAvailable>
<Description>{description}</Description>
<DeveloperName>{the name of the developer}</DeveloperName>
<Downloads>{number of downloads}</Downloads>
<Format>{the original format}</Format>
<Keywords>{comma separated list}</Keywords>
<Label>{label}</Label>
<MissingTextures>{list of texture names}</MissingTextures>
<MoreInformationURL>{url}</MoreInformationURL>
<NumPolygons>{int}</NumPolygons>
<NumTextures>{int}</NumTextures>
<PID>{pid}</PID>
<Revision>{current revision}</Revision>
<SponsorName>{the name of the sponsor}</SponsorName>
<SupportingFiles>{list of supporting assets}</SupportingFiles>
<TextureReferences>{list of texture names}</TextureReferences>
<Title>{title}</Title>
<TotalRevisions>{total number of revisions}</TotalRevisions>
<UnitScale>{int}</UnitScale>
<UpAxis>{Y or Z}</UpAxis>
<UploadedDate>{date}</UploadedDate>
<Views>{int}</Views>
<_3dsLink>http://...</_3dsLink>
<_OriginalUploadLink>http://...</_OriginalUploadLink>
<_ReviewsLink>http://...</_ReviewsLink>
<_ScreenshotLink>http://...</_ScreenshotLink
<_ThumbnailLink>http://...</_ThumbnailLink>
<_fbxLink>http://...</_fbxLink>
<_jsonLink>http://...</_jsonLink>
<_o3dLink>http://...</_o3dLink>
<_objLink>http://...</_objLink>
</Metadata>
Get an JSON encoded metadata structure for the given pid
{
AnonymousDownloadAvailable: true or false,
ArtistName: "{the name of the artist}",
AssetType: "{Model}",
ConversionAvailable true or false,
Description: "{description}",
DeveloperName: "{the name of the developer}",
Downloads: "{number of downloads}",
Format: "{the original format}",
Keywords: "{comma separated list}",
Label: "{label}",
MissingTextures: "{list of texture names}",
MoreInformationURL: "{url}",
NumPolygons: "{int}",
NumTextures: "{int}",
PID: "{pid}",
Revision: "{current revision}",
SponsorName: "{the name of the sponsor}",
SupportingFiles: "{list of supporting assets}",
TextureReferences: "{list of texture names}",
Title: "{title}",
TotalRevisions: "{total number of revisions}",
UnitScale: "{int}",
UpAxis: "{Y or Z}",
UploadedDate: "{date}",
Views: "{int}"
_3dsLink: Download link for 3ds format file,
_OriginalUploadLink: Download link for the originally uploaded file,
_ReviewsLink: Link to the reviews for this object
_ScreenshotLink: Download link for screenshot file,
_ThumbnailLink: Download link for thumbnail file,
_fbxLink: Download link for fbx format file,
_jsonLink: Download link for json format file,
_o3dLink: Download link for o3d format file,
_objLink: Download link for obj format file,
}
A Texture Reference (Either missing or found) looks like this in JSON
{
_Link: null for missing texture, a link for existing textures,
mFilename: The name of the file,
mType: unknown, reserved for future use,
mUVSet: The UV Channel this texture uses
}
And like this in XML
<Texture> <_Link >link </Link> <mFilename>none</mFilename> <mType>unknown</mType> <mUVSet>0</mUVSet> </Texture>
Use JSONP to get the metadata. Returns the JSON object above. Use this when making cross domain AJAX requests.
Get an XML encoded array of the reviews for this pid. The format of the returned XML will be:
<ArrayOfReview>
<Review>
<DateTime>{date submitted}</DateTime>
<Rating>{the number of stars selected}</Rating>
<ReviewText>{the text of the comment}</ReviewText>
<Submitter>{the email of the commenter}</Submitter>
</Review>
</ArrayOfReview>
Get a JSON encoded array of the reviews for this pid. The format of the returned JSON will be:
[
{
DateTime: "{date submitted}",
Rating: "{number of stars}",
ReviewText: "{text of review}",
Submitter: "{email of reviewer}"
}
]
Use JSONP to get the reviews. Returns the same JSON structure as above. Use this when making cross domain AJAX requests.
This function can be used to retrieve the binary data associated with a model. The binary file will be a zip file in all cases except for when format is O3D. The format parameter will cause the delivered zip to contain the model in different formats. In the case where format=O3D, the file will be a .o3dtgz archive.
Format string Type returned dae Collada fbx Autodesk FBX obj Wavefront OBJ. An additional .mtl file will be created to contain the textures 3ds Autodesk 3DS json A Javascript object containing the scenegraph in OSGJS format o3dtgz An O3Dtgz archive generated with the Google O3D converter.
This function will return the screenshot image file associated with the model.
This function will return the sponsor logo image file associated with the model.
This function will return the developer logo image file associated with the model.
This function will return the file originally uploaded by the user. This file will contain the unconverted 3D model, all textures, and anything else the submitter may have included. These files are not validated by the system and may contain malicious content.
This will retrieve a binary stream for a supporting document submitted for a model. Note that this cannot be used to fetch a file from within the archive. Supporting files are uploaded and stored separately from the model data. They are expected to be reference artwork, related diagrams and other supporting work. These files are not validated by the system and may contain malicious content.
This will retrieve a binary stream for a texture file referenced by a model. These files are image files that are loaded by the model file. Image files included in the archive that are not referenced by the model file cannot be retrieved with this function. Retrieve the metadata for the model to find the names of texture files referenced by the model. These files are not validated by the system and may contain malicious content.
This returns a JSON structure that describes the service. The values for the organization name and url come from the Web.config of the services project, and can be configured from the Web Front End project. The JSON returned looks like
{
"AccessJSON": "http://3dr.adlnet.gov/api/_3DRAPI.svc/pid:0/Metadata/json?ID=00-00-00",
"AccessJSONP": "http://3dr.adlnet.gov/api/_3DRAPI.svc/pid:0/Metadata/json?ID=00-00-00&callback=callme",
"AccessXML": "http://3dr.adlnet.gov/api/_3DRAPI.svc/pid:0/Metadata/xml?ID=00-00-00",
"Namespace": "adl",
"OrganizationName": null,
"OrganizationPOC": null,
"OrganizationPOCEmail": null,
"OrganizationURL": null,
"SearchJSON": "http://3dr.adlnet.gov/api/_3DRAPI.svc/Search/term/json?ID=00-00-00",
"SearchJSONP": "http://3dr.adlnet.gov/api/_3DRAPI.svc/Search/term/jsonp?ID=00-00-00&callback=callme",
"SearchXML": "http://3dr.adlnet.gov/api/_3DRAPI.svc/Search/term/xml?ID=00-00-00",
"Upload": "http://3dr.adlnet.gov/api/_3DRAPI.svc/UploadFile?ID=00-00-00"
}
Get the permission level a given group has for this model. Anyone can request this value. Returns either XML or JSON.
Get the permission level a given user has for this model. Anyone can request this value. Returns either XML or JSON.
Set the permission for a given user on this model. The level should be a number from 0 to 4, corresponding to the permission levels listed above. The user requesting this change must have Edit permissions on this object.
Set the permission for a given group on this model. The level should be a number from 0 to 4, corresponding to the permission levels listed above. The user requesting this change must have Edit permissions on this object, must be the owner of the group, or must be a member of the group when the group is marked as “MembersAdd”.
Overwrite the metadata for an existing object. You must use Basic Auth and have permissions to edit the object. The body of the post should be formatted as either XML or JSON as shown in the GET Metadata URI above. Not all fields in the Metadata structure will be saved - for instance, you cannot overwrite the submitter field. Still, these fields should be included so that the object will serialize correctly.
Add a review to a model. You must use Basic Auth and be a member of the site - Anonymous Users are not allowed to review. The review submitter will be set as the user from the Auth headers. The posted data should be a json or xml structure as shown in the GET Reviews URI.
Upload a new model to the site. This will trigger the conversion process and store the object as well as the converted files. You must use authentication and have an account on the site. The return value will be a plain string surrounded by quotation marks that identifies the PID of the new model.
Overwrite the existing model with a new file. This will re-convert the file, and store it. Future versions of the software may create version-ed copies of the data. The body of the post should be the raw binary of the ZIP file that contains the model.
This will store and set the screenshot file for the model. You must use Basic Auth, and the user must have Edit permissions to call this. The body of the post should be the raw binary of the image file. The Thumbnail will be automatically generated from the screenshot.
Upload a texture to a model. This can only be used to upload textures marked as ‘missing’ in the object metadata. The filename of the uploaded model should be in the ‘Content-disposition’ header, in the format ‘filename={the name of the file}’. The body of the post should be the raw binary of the image file to upload.
Upload a supporting file to the model - this is any other document that you wish to be associated with the content. The name of the file should be stored in the ‘Content-disposition’ header, in the format ‘filename={the name of the file}’. Files with the same name as existing Supporting Files will overwrite existing files. You must have Edit permissions on an object to call this function. The Description parameter is used to store a human readable descriptive text. The body should be the raw binary of the file to upload.
These examples show the use of the API, substituting real values for the parameters described above. You can paste them into a browser to see the results.
Search the ADL copy of the 3DR for models with military in either the name or description. Return XML data.
Get the metadata for the model “HWMMVE” from the main 3DR instance in json format.
Use JSONP to get the review in JSON format. The result is a string that can be evaluated as javascript by a browsers. Use this with AJAX to request JSON from a 3DR server on a different domain.
Download the “Coffee table” model as a COLLADA zip file
Download the “Coffee table” model as a fbx file but not in a zip.
Get the texture “teak_aruba.jpg” from the “Coffee Table” model.
Get the data that was originally sent to the server by the uploader. This data is unmodified by the 3DR, and may be the only data available if conversion for a model failed.
Notice that the server challenges you to provide credentials to download this model. This is because the model is not marked as accessible to anonymous download. If you have an account on the 3DR demo instance, use your name and password here to access this model.