AssetService

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(→‎GET:/assets)
 
(23 intermediate revisions by one user not shown)
Line 1: Line 1:
 
=Introduction=
 
=Introduction=
  
−
The OpenSimulator asset services stores asset data (textures, serialized objects, scripts, etc.) and provides this on request.
+
The OpenSimulator asset service stores asset data (textures, serialized objects, scripts, etc.) and provides this on request.
  
 
=API=
 
=API=
  
−
==GET:/assets==
+
==GET /assets==
  
 
Uri format is
 
Uri format is
Line 17: Line 17:
 
There is no content in the request body.
 
There is no content in the request body.
  
−
Sample return data
+
If the asset was not found, you will receive a 404 status code response with an empty body.
 +
 
 +
If the asset was found then asset data will be returned.  Sample return data is
  
 
<pre>
 
<pre>
Line 27: Line 29:
 
   </FullID>
 
   </FullID>
 
   <ID>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</ID>
 
   <ID>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</ID>
−
   <Name>terrainImage_bbbbbbbb-bf88-45ac-aace-35bd76426c81</Name>
+
   <Name>test texture</Name>
 
   <Description>test one</Description>
 
   <Description>test one</Description>
 
   <Type>0</Type>
 
   <Type>0</Type>
Line 33: Line 35:
 
   <Temporary>false</Temporary>
 
   <Temporary>false</Temporary>
 
   <CreatorID>bbbbbbbb-bf88-45ac-aace-35bd76426c81</CreatorID>
 
   <CreatorID>bbbbbbbb-bf88-45ac-aace-35bd76426c81</CreatorID>
−
   <Flags>Maptile</Flags>
+
   <Flags>Normal</Flags>
 
</AssetBase>
 
</AssetBase>
 
</pre>
 
</pre>
Line 47: Line 49:
 
* '''Local''' - true or false.  In other contexts signals whether asset is local to that simulator only.  In the context of the asset service this should always be false.
 
* '''Local''' - true or false.  In other contexts signals whether asset is local to that simulator only.  In the context of the asset service this should always be false.
 
* '''Temporary''' - true or false.  Signals whether the asset should be treated as temporary (and so can be removed on simulator restart) or permanent (which is the usual case).
 
* '''Temporary''' - true or false.  Signals whether the asset should be treated as temporary (and so can be removed on simulator restart) or permanent (which is the usual case).
−
* '''CreatorID''' - The UUID of the entity that created the asset.
+
* '''CreatorID''' - The ID of the entity that created the asset.  Often a UUID but not mandatory.  This is not actively used but can be useful in debugging.
 
* '''Flags''' - Multiple flags must be comma separated (e.g. <Flags>Maptile,Collectable</Flags>).  Each flag can have leading or trailing whitespace (e.g. <Flags>Maptile,Collectable</Flags>).  Possible flags are
 
* '''Flags''' - Multiple flags must be comma separated (e.g. <Flags>Maptile,Collectable</Flags>).  Each flag can have leading or trailing whitespace (e.g. <Flags>Maptile,Collectable</Flags>).  Possible flags are
 
** Normal - Normal non-maptile immustable asset.
 
** Normal - Normal non-maptile immustable asset.
Line 54: Line 56:
 
** Collectable - Asset can be removed after some time (this is poorly defined and may not currently be used).
 
** Collectable - Asset can be removed after some time (this is poorly defined and may not currently be used).
  
−
==POST:/assets==
+
One should not rely on this element order.  One should also be prepared to ignore or otherwise deal with extra elements.
 +
 
 +
===Sample scripts===
 +
<source lang="python">
 +
#!/usr/bin/python
 +
 
 +
import httplib
 +
 
 +
conn = httplib.HTTPConnection("localhost", 8003);
 +
conn.request("GET", "/assets/f87f97ff-a493-4fb6-b263-1c8a0f1efc11")
 +
response = conn.getresponse()
 +
print "Status:" + str(response.status)
 +
print response.read();
 +
</source>
 +
 
 +
==POST /assets==
  
 
Uri format is
 
Uri format is
Line 66: Line 83:
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
−
<AssetBase xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
<AssetBase>
 
   <Data>/0//UQAvAAAAAAEAAAABAAAAAAAAAAAAAA...</Data>
 
   <Data>/0//UQAvAAAAAAEAAAABAAAAAAAAAAAAAA...</Data>
 
   <FullID>
 
   <FullID>
Line 72: Line 89:
 
   </FullID>
 
   </FullID>
 
   <ID>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</ID>
 
   <ID>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</ID>
−
   <Name>terrainImage_bbbbbbbb-bf88-45ac-aace-35bd76426c81</Name>
+
   <Name>test texture</Name>
 
   <Description>test one</Description>
 
   <Description>test one</Description>
 
   <Type>0</Type>
 
   <Type>0</Type>
−
  <Local>false</Local>
 
−
  <Temporary>false</Temporary>
 
−
  <CreatorID>bbbbbbbb-bf88-45ac-aace-35bd76426c81</CreatorID>
 
−
  <Flags>Maptile</Flags>
 
 
</AssetBase>
 
</AssetBase>
 
</pre>
 
</pre>
Line 90: Line 103:
 
* '''Description''' - Description of asset.  This is not actively used but can be useful in debugging.  Maximum size is 64 characters.
 
* '''Description''' - Description of asset.  This is not actively used but can be useful in debugging.  Maximum size is 64 characters.
 
* '''Type''' - Type of asset.  An integer that comes from [https://github.com/openmetaversefoundation/libopenmetaverse/blob/master/OpenMetaverseTypes/Enums.cs OpenMetaverse.AssetType].
 
* '''Type''' - Type of asset.  An integer that comes from [https://github.com/openmetaversefoundation/libopenmetaverse/blob/master/OpenMetaverseTypes/Enums.cs OpenMetaverse.AssetType].
−
* '''Local''' - true or false.  In other contexts signals whether asset is local to that simulator only.  In the context of the asset service this should always be false.
+
* '''Local''' - true or false.  Optional, defaults to false.  In other contexts signals whether asset is local to that simulator only.  In the context of the asset service this should always be false.
−
* '''Temporary''' - true or false.  Signals whether the asset should be treated as temporary (and so can be removed on simulator restart) or permanent (which is the usual case).
+
* '''Temporary''' - true or false.  Options, defaults to false.  Signals whether the asset should be treated as temporary (and so can be removed on simulator restart) or permanent (which is the usual case).
−
* '''CreatorID''' - The UUID of the entity that created the asset.
+
* '''CreatorID''' - The ID of the entity that created the asset.  Optional, the default is blank.  Often a UUID but not mandatory.  This is not actively used but can be useful in debugging.
−
* '''Flags''' - Multiple flags must be comma separated (e.g. <Flags>Maptile,Collectable</Flags>).  Each flag can have leading or trailing whitespace (e.g. <Flags>Maptile,Collectable</Flags>).  Possible flags are
+
* '''Flags''' - Multiple flags must be comma separated (e.g. <Flags>Maptile,Collectable</Flags>).  Each flag can have leading or trailing whitespace (e.g. <Flags>Maptile,Collectable</Flags>).  Optional, the default is Normal.  Possible flags are
 
** Normal - Normal non-maptile immustable asset.
 
** Normal - Normal non-maptile immustable asset.
 
** Maptile - Maptile asset.
 
** Maptile - Maptile asset.
Line 99: Line 112:
 
** Collectable - Asset can be removed after some time (this is poorly defined and may not currently be used).
 
** Collectable - Asset can be removed after some time (this is poorly defined and may not currently be used).
  
−
Returns '''TODO'''
+
The order of elements is not important.
  
−
==DELETE:/assets==
+
If the request is well-formed XML, then data in the form.
 +
 
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<string>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</string>
 +
 
 +
is always returned where string contains the UUID of the asset posted.
 +
 
 +
From OpenSimulator 0.7.5 onwards, an HTTP status code of 400 (Bad Request) will be returned if the XML is not well-formed.  In OpenSimulator 0.7.4 and previously, the simulator would simply drop the request and not respond.
 +
 
 +
=== Sample scripts===
 +
====Python====
 +
 
 +
<source lang="python">
 +
#!/usr/bin/python
 +
 
 +
import base64
 +
import httplib
 +
import sys
 +
import xml.dom.minidom as md
 +
from xml.etree.cElementTree import Element, ElementTree, tostring
 +
 
 +
idString = "f87f97ff-a493-4fb6-b263-1c8a0f1efc12"
 +
 
 +
assetBaseElement = Element("AssetBase")
 +
 
 +
dataElement = Element("Data")
 +
dataElement.text = base64.b64encode("Dummy data")
 +
assetBaseElement.append(dataElement)
 +
 
 +
fullIdElement = Element("FullID")
 +
guidElement = Element("Guid")
 +
guidElement.text = idString
 +
fullIdElement.append(guidElement)
 +
assetBaseElement.append(fullIdElement)
 +
 
 +
idElement = Element("ID")
 +
idElement.text = idString
 +
assetBaseElement.append(idElement)
 +
 
 +
nameElement = Element("Name")
 +
nameElement.text = "test texture"
 +
assetBaseElement.append(nameElement)
 +
 
 +
descriptionElement = Element("Description")
 +
descriptionElement.text = "test one"
 +
assetBaseElement.append(descriptionElement)
 +
 
 +
typeElement = Element("Type")
 +
typeElement.text = "0"
 +
assetBaseElement.append(typeElement)
 +
 
 +
doc = ElementTree(assetBaseElement)
 +
rawXml = tostring(assetBaseElement)
 +
 
 +
mdDoc = md.parseString(rawXml)
 +
print mdDoc.toprettyxml()
 +
 
 +
conn = httplib.HTTPConnection("localhost", 8003);
 +
conn.request("POST", "/assets", rawXml)
 +
response = conn.getresponse()
 +
print response.read();
 +
</source>
 +
 
 +
==DELETE /assets==
  
 
'''TODO'''
 
'''TODO'''
 +
 +
==POST /get_assets_exist==
 +
 +
Returns whether assets exist in the assets database.
 +
 +
====Request====
 +
 +
The Uri doesn't have any parameters in the path.
 +
 +
The request body contains a list of Asset UUID's.
 +
 +
Sample request body:
 +
 +
<pre>
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<ArrayOfString xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 +
    <string>cdad34d4-2227-4356-b4a1-7f6a91836d2d</string>
 +
    <string>89556747-24cb-43ed-920b-47caed15465f</string>
 +
</ArrayOfString>
 +
</pre>
 +
 +
====Response====
 +
 +
For each asset, returns whether it exists or not (true/false).
 +
 +
Sample response:
 +
 +
<pre>
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<ArrayOfBoolean xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 +
    <boolean>true</boolean>
 +
    <boolean>false</boolean>
 +
</ArrayOfBoolean>
 +
</pre>
 +
 +
====Notes====
 +
 +
Added in OpenSimulator 0.8.0. Older versions will return an error code because they don't support this request. That response is equivalent to returning 'false' for all the assets.

Latest revision as of 03:41, 3 April 2014

Contents

[edit] Introduction

The OpenSimulator asset service stores asset data (textures, serialized objects, scripts, etc.) and provides this on request.

[edit] API

[edit] GET /assets

Uri format is 

/assets/<asset-uuid>

e.g. 

/assets/e0eb480b-e405-491d-8ed1-6d0ababe822c

There is no content in the request body.

If the asset was not found, you will receive a 404 status code response with an empty body.

If the asset was found then asset data will be returned. Sample return data is 

<?xml version="1.0" encoding="utf-8"?>
<AssetBase>
  <Data>/0//UQAvAAAAAAEAAAABAAAAAAAAAAAAAA...</Data>
  <FullID>
    <Guid>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</Guid>
  </FullID>
  <ID>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</ID>
  <Name>test texture</Name>
  <Description>test one</Description>
  <Type>0</Type>
  <Local>false</Local>
  <Temporary>false</Temporary>
  <CreatorID>bbbbbbbb-bf88-45ac-aace-35bd76426c81</CreatorID>
  <Flags>Normal</Flags>
</AssetBase>

where

  • Data - Base64 encoding of the asset data. No maximum length.
  • FullID - UUID of the asset. This is identical to ID for historical reasons.
  • ID UUID of the asset. This is identical to ID for historical reasons.
  • Name - the name of the asset in the database. This is not actively used since assets are referred to by their inventory names. Can be useful for debugging purposes. Maximum size is 64 characters.
  • Description - Description of asset. This is not actively used but can be useful in debugging. Maximum size is 64 characters.
  • Type - Type of asset. An integer that comes from OpenMetaverse.AssetType.
  • Local - true or false. In other contexts signals whether asset is local to that simulator only. In the context of the asset service this should always be false.
  • Temporary - true or false. Signals whether the asset should be treated as temporary (and so can be removed on simulator restart) or permanent (which is the usual case).
  • CreatorID - The ID of the entity that created the asset. Often a UUID but not mandatory. This is not actively used but can be useful in debugging.
  • Flags - Multiple flags must be comma separated (e.g. <Flags>Maptile,Collectable</Flags>). Each flag can have leading or trailing whitespace (e.g. <Flags>Maptile,Collectable</Flags>). Possible flags are
    • Normal - Normal non-maptile immustable asset.
    • Maptile - Maptile asset.
    • Rewritable - Content can be rewritten
    • Collectable - Asset can be removed after some time (this is poorly defined and may not currently be used).

One should not rely on this element order. One should also be prepared to ignore or otherwise deal with extra elements.

[edit] Sample scripts

#!/usr/bin/python
 
import httplib
 
conn = httplib.HTTPConnection("localhost", 8003);
conn.request("GET", "/assets/f87f97ff-a493-4fb6-b263-1c8a0f1efc11")
response = conn.getresponse()
print "Status:" + str(response.status)
print response.read();

[edit] POST /assets

Uri format is 

/assets

e.g.

Sample request body 

<?xml version="1.0" encoding="utf-8"?>
<AssetBase>
  <Data>/0//UQAvAAAAAAEAAAABAAAAAAAAAAAAAA...</Data>
  <FullID>
    <Guid>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</Guid>
  </FullID>
  <ID>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</ID>
  <Name>test texture</Name>
  <Description>test one</Description>
  <Type>0</Type>
</AssetBase>

where

  • Data - Base64 encoding of the asset data. No maximum length.
  • FullID - UUID of the asset. This is identical to ID for historical reasons.
  • ID UUID of the asset. This is identical to ID for historical reasons.
  • Name - the name of the asset in the database. This is not actively used since assets are referred to by their inventory names. Can be useful for debugging purposes. Maximum size is 64 characters.
  • Description - Description of asset. This is not actively used but can be useful in debugging. Maximum size is 64 characters.
  • Type - Type of asset. An integer that comes from OpenMetaverse.AssetType.
  • Local - true or false. Optional, defaults to false. In other contexts signals whether asset is local to that simulator only. In the context of the asset service this should always be false.
  • Temporary - true or false. Options, defaults to false. Signals whether the asset should be treated as temporary (and so can be removed on simulator restart) or permanent (which is the usual case).
  • CreatorID - The ID of the entity that created the asset. Optional, the default is blank. Often a UUID but not mandatory. This is not actively used but can be useful in debugging.
  • Flags - Multiple flags must be comma separated (e.g. <Flags>Maptile,Collectable</Flags>). Each flag can have leading or trailing whitespace (e.g. <Flags>Maptile,Collectable</Flags>). Optional, the default is Normal. Possible flags are
    • Normal - Normal non-maptile immustable asset.
    • Maptile - Maptile asset.
    • Rewritable - Content can be rewritten
    • Collectable - Asset can be removed after some time (this is poorly defined and may not currently be used).

The order of elements is not important.

If the request is well-formed XML, then data in the form.

<?xml version="1.0" encoding="utf-8"?> <string>f87f97ff-a493-4fb6-b263-1c8a0f1efc12</string>

is always returned where string contains the UUID of the asset posted.

From OpenSimulator 0.7.5 onwards, an HTTP status code of 400 (Bad Request) will be returned if the XML is not well-formed. In OpenSimulator 0.7.4 and previously, the simulator would simply drop the request and not respond.

[edit] Sample scripts

[edit] Python

#!/usr/bin/python
 
import base64
import httplib
import sys 
import xml.dom.minidom as md
from xml.etree.cElementTree import Element, ElementTree, tostring
 
idString = "f87f97ff-a493-4fb6-b263-1c8a0f1efc12"
 
assetBaseElement = Element("AssetBase")
 
dataElement = Element("Data")
dataElement.text = base64.b64encode("Dummy data")
assetBaseElement.append(dataElement)
 
fullIdElement = Element("FullID")
guidElement = Element("Guid")
guidElement.text = idString
fullIdElement.append(guidElement)
assetBaseElement.append(fullIdElement)
 
idElement = Element("ID")
idElement.text = idString
assetBaseElement.append(idElement)
 
nameElement = Element("Name")
nameElement.text = "test texture"
assetBaseElement.append(nameElement)
 
descriptionElement = Element("Description")
descriptionElement.text = "test one"
assetBaseElement.append(descriptionElement)
 
typeElement = Element("Type")
typeElement.text = "0" 
assetBaseElement.append(typeElement)
 
doc = ElementTree(assetBaseElement)
rawXml = tostring(assetBaseElement)
 
mdDoc = md.parseString(rawXml)
print mdDoc.toprettyxml()
 
conn = httplib.HTTPConnection("localhost", 8003);
conn.request("POST", "/assets", rawXml)
response = conn.getresponse()
print response.read();

[edit] DELETE /assets

TODO

[edit] POST /get_assets_exist

Returns whether assets exist in the assets database.

[edit] Request

The Uri doesn't have any parameters in the path.

The request body contains a list of Asset UUID's.

Sample request body: 

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfString xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <string>cdad34d4-2227-4356-b4a1-7f6a91836d2d</string>
    <string>89556747-24cb-43ed-920b-47caed15465f</string>
</ArrayOfString>

[edit] Response

For each asset, returns whether it exists or not (true/false).

Sample response: 

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfBoolean xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <boolean>true</boolean>
    <boolean>false</boolean>
</ArrayOfBoolean>

[edit] Notes

Added in OpenSimulator 0.8.0. Older versions will return an error code because they don't support this request. That response is equivalent to returning 'false' for all the assets.

Retrieved from "http://opensimulator.org/index.php?title=AssetService&oldid=38712"
Personal tools
General
About This Wiki