1.4. Links and references

Often resources need to refer to other resources. For example, when creating a server, you must specify the image from which to build the server. You can specify the image by providing an ID or a URL to a remote image. When providing an ID, it is assumed that the resource exists in the current OpenStack deployment.

Example 1.4. ID image reference: JSON request

{
   "server":{
      "flavorRef":"http://openstack.example.com/openstack/flavors/1",
      "imageRef":"http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
      "metadata":{
         "My Server Name":"Apache1"
      },
      "name":"new-server-test",
      "personality":[
         {
            "contents":"ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
            "path":"/etc/banner.txt"
         }
      ]
   }
}

Example 1.5. ID image reference: XML request

<?xml version="1.0" encoding="UTF-8"?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1"
        xmlns:atom="http://www.w3.org/2005/Atom"
        name="new-server-test"
        imageRef="52415800-8b69-11e0-9b19-734f6f006e54"
        flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
        >
  <metadata>
    <meta key="My Server Name">Apache1</meta>
  </metadata>
  <personality>
    <file path="/etc/banner.txt">
        ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
        dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
        IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
        c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
        QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
        ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
        dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
        c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
        b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
    </file>
  </personality>
</server>

Example 1.6. Full image reference: JSON request

{
   "server":{
      "flavorRef":"http://openstack.example.com/openstack/flavors/1",
      "imageRef":"http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
      "metadata":{
         "My Server Name":"Apache1"
      },
      "name":"new-server-test",
      "personality":[
         {
            "contents":"ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
            "path":"/etc/banner.txt"
         }
      ],
      "networks":[
         {
            "uuid":"c6a48469-4638-4346-b755-6e66ed7abdff",
            "fixed_ip":"10.0.0.10"
         }
      ]
   }
}

Example 1.7. Full image reference: XML request

<?xml version='1.0' encoding='UTF-8'?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1"
  imageRef="http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b"
  flavorRef="http://openstack.example.com/openstack/flavors/1"
  name="new-server-test">
  <metadata>
    <meta key="My Server Name">Apache1</meta>
  </metadata>
  <personality>
    <file path="/etc/banner.txt">
      ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
      dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
      IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
      c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
      QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
      ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
      dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
      c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
      b25zLiINCg0KLVJpY2hhcmQgQmFjaA== </file>
  </personality>
  <networks>
      <network uuid="c6a48469-4638-4346-b755-6e66ed7abdff" fixed_ip="10.0.0.10"/>
  </networks>
</server>

For convenience, resources contain links to themselves. This allows a client to easily obtain rather than construct resource URIs. The following types of link relations are associated with resources:

A self link contains a versioned link to the resource. Use these links when the link will be followed immediately.
A bookmark link provides a permanent link to a resource that is appropriate for long term storage.
An alternate link can contain an alternate representation of the resource. For example, an OpenStack Compute image might have an alternate representation in the OpenStack Image service.

	Note
	The type attribute provides a hint as to the type of representation to expect when following the link.

Example 1.8. Server with self links: JSON

{
    "server" : {
        "id" : "52415800-8b69-11e0-9b19-734fcece0043",
        "name" : "my-server",
        "links": [
            {
                "rel" : "self",
                "href" : "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"
            },
            {
                "rel" : "bookmark",
                "href" : "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"
            }
        ]
    }
}

Example 1.9. Server with self links: XML

<?xml version="1.0" encoding="UTF-8"?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1"
        xmlns:atom="http://www.w3.org/2005/Atom"
        id="52415800-8b69-11e0-9b19-734fcece0043" name="my-server">
  <atom:link
      rel="self"
      href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"/>
  <atom:link
      rel="bookmark"
      href="http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"/>
</server>

Example 1.10. Server with alternate link: JSON

{
    "image" : {
        "id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
        "name" : "My Server Backup",
        "links": [
            {
                "rel" : "self",
                "href" : "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
            },
            {
                "rel" : "bookmark",
                "href" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
            },
            {
                "rel"  : "alternate",
                "type" : "application/vnd.openstack.image",
                "href" : "http://glance.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
            }
        ]
    }
}

Example 1.11. Image with alternate link: XML

<?xml version="1.0" encoding="UTF-8"?>
<image
    xmlns="http://docs.openstack.org/compute/api/v1.1"
    xmlns:atom="http://www.w3.org/2005/Atom"
    id="52415800-8b69-11e0-9b19-734f5736d2a2"
    name="My Server Backup">
    <atom:link
        rel="self"
        href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"/>
    <atom:link
        rel="bookmark"
        href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"/>
    <atom:link
        rel="alternate" type="application/vnd.openstack.image"
        href="http://glance.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"/>
</image>

Questions? Discuss on ask.openstack.org
Found an error? Report a bug against this page

Legal notices