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

{
    "server": {
        "name": "new-server-test",
        "image": "52415800-8b69-11e0-9b19-734f6f006e54",
        "flavor": "52415800-8b69-11e0-9b19-734f1195ff37",
        "metadata": {
            "My Server Name": "Apache1"
        },
        "personality": [
            {
                "path": "/etc/banner.txt",
                "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
                             dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k 
                             IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs 
                             c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g 
                             QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo 
                             ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv 
                             dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy 
                             c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 
                             b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ]
    }
}

Example 1.5. ID Image Reference: 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"
        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

{
    "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": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
                             dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
                             IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
                             c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
                             QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
                             ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
                             dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
                             c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
                             b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
                "path": "/etc/banner.txt"
            }
        ]
    }
}

Example 1.7. Full Image Reference: XML

<?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>
</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 that the type attribute here is used to provide 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>

Legal notices