• Buy Now
    • Rackspace Cloud
    • Email & Apps
    • Fanatical Support for AWS
    • Managed Google Cloud Platform
    • Office 365
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Cloud Office Control Panel
  • Rackspace Logo
  • Developer Home
  • Developer Documentation
  • Blogs ▼
    • Technical Blog
    • Rackspace Blog
  • Support Documentation

Developer Docs


Let’s Build Something Powerful Together!

Submit an issue
  • Cloud Images 2.0
  • Getting started
    • Get your credentials
    • Send API requests to Rackspace Cloud Images
      • Convert cURL examples to run on Windows
    • Authenticate to the Rackspace Cloud
      • Send an authentication request
      • Review the authentication response
      • Configure environment variables
    • Concepts
      • Images
        • Standard images
        • Nonstandard images
      • Image entities
      • Image identifiers
      • Image properties
      • Image sharing
        • Sample workflow for image sharing, after image creation
      • Asynchronous tasks
        • High-level process for importing an image
        • High-level process for exporting an image
      • Statuses
        • Image statuses
        • Task statuses
        • Image member statuses
      • HTTP PATCH method
        • Restricted JSON pointers
        • Using the HTTP PATCH method
        • HTTP PATCH add operation
        • HTTP PATCH remove operation
        • HTTP PATCH replace operation
    • Use images
      • Listing images
      • Getting details for an image
      • Updating an image
      • Importing an image by using tasks
      • Exporting an image by using tasks
      • Getting details for a task
    • Share images
      • Creating an image member
      • Listing image members
      • Getting image member details
      • Updating an image member
      • Deleting an image member
  • General API information
    • Service access endpoints
    • Request and response types
      • Media Types
      • JSON Schemas
    • Paginated collections
    • Date and time format
    • Role-based access control (RBAC)
      • Assigning roles to account users
      • Roles available for Cloud Images
      • Multiproduct global roles and permissions
      • Resolving conflicts between RBAC multiproduct and product-specific roles
      • RBAC permissions cross-reference to Cloud Images API operations
  • API reference
    • Images
      • List images
        • Request
        • Response
      • Get image details
        • Request
        • Response
      • Update image
        • Request
        • Response
      • Delete image
        • Request
        • Response
    • Image sharing
      • List image members
        • Request
        • Response
      • Get image member details
        • Request
        • Response
      • Create image member
        • Request
        • Response
      • Delete image member
        • Request
        • Response
      • Update image member
        • Request
        • Response
    • Image tag
      • Add image tag
        • Request
        • Response
      • Delete image tag
        • Request
        • Response
    • Image task
      • List tasks
        • Request
        • Response
      • Get task details
        • Request
        • Response
      • Task to import image
        • Request
        • Response
      • Task to export image
        • Request
        • Response
    • JSON schemas
      • Get images schema
        • Request
        • Response
      • Get image schema
        • Request
        • Response
      • Get image members schema
        • Request
        • Response
      • Get image member schema
        • Request
        • Response
      • Get task schema
        • Request
        • Response
      • Get tasks schema
        • Request
        • Response
  • Glossary
  • Release Notes
    • API v2.0 release, September 9, 2013
      • What's new
      • Resolved issues
      • Known issues
  • Service updates
  • Additional resources
  • Disclaimer

Share images#

The Cloud Images API enables image owners to share images that they have created with others and to use images created by someone else. See Image sharing to learn more about the fundamental concepts.

The following sections show some basic image sharing operations with cURL examples.

Note

The user with whom the image is being shared in these examples is identified by a member_id, which is the same as that user's tenant_id.

To help you get started exploring Cloud Images, the following sections show some basic image operations with cURL examples.

Before running the examples, review the Cloud Images concepts.

Note

These examples use the $API_ENDPOINT and $AUTH_TOKEN environment variables to specify the API endpoint and authentication token values for accessing the service. Make sure you configure these variables before running the code samples.

Creating an image member#

To share an image with a particular user, you need to know who the user is, create an image member for that user, and associate the image member with the image.

Issue the following cURL command to create an image member for an image. In this example, you share the image a96be11e-8536-4910-92cb-de50aa19dfe6, which you created, with user 123456. You might have blogged about your image, and the user emailed you requesting access, so you know the user's user ID and can use it as the value for the member parameter.

Create an image member with cURL request

curl -s $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members \
-X POST \
-d '{"member":"123456"}' -H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type:application/json" |python -m json.tool

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.
  • -s: Runs the command in silent mode.
  • -H: Specified header information. In this case, it provides the content type and the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
  • -d: Specifies the JSON request body.
  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Create an image member with cURL response

{
   "created_at": "2013-09-20T19:22:19Z",
   "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
   "member_id": "123456",
   "schema": "/v2/schemas/member",
   "status": "pending",
   "updated_at": "2013-09-20T19:25:31Z"
}

Listing image members#

If you want to see everyone with whom you've shared an image and the status of each member, list the image members.

  • Issue the following cURL command to list the image members for an image. In this example, you list members for image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL list image members request

curl -s API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members \
-H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool

Options:

  • -s: Runs the command in silent mode.
  • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

List image members with cURL response

{
    "members": [
        {
            "created_at": "2013-10-07T17:58:03Z",
            "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
            "member_id": "123456",
            "schema": "/v2/schemas/member",
            "status": "pending",
            "updated_at": "2013-10-07T17:58:03Z"
        },
        {
            "created_at": "2013-10-07T17:58:55Z",
            "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
            "member_id": "9876543",
            "schema": "/v2/schemas/member",
            "status": "accepted",
            "updated_at": "2013-10-08T12:08:55Z"
        }
    ],
    "schema": "/v2/schemas/members"
}

Getting image member details#

If you want to see details for a specific image member, get the image member's details.

  • Issue the following cURL command to get the image member's details. In this example, you list details for member 123456 of image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL get image member details request

curl -s $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members/123456 \
-H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool

Options:

  • -s: Runs the command in silent mode.
  • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Get image member details response

{
    "created_at": "2013-10-07T17:58:03Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "123456",
    "schema": "/v2/schemas/member",
    "status": "pending",
    "updated_at": "2013-10-07T17:58:03Z"
}

Updating an image member#

If you send a request, outside of the Cloud Images API, to an image producer asking for access to an image, the image producer creates an image member with your tenant ID by using the instructions in Create an image member. Once the image member has been created for you, you update the image member, either accepting the image (which adds it to your image list), or rejecting the image (which notifies the producer that you received the image share notification and don't want it in your image list).

Tip

For more information about image member statuses, see Image member statuses.

Issue the following cURL command to update an image member for an image. In this example, you (member ID 123456) accept the offer of the shared image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL update an image member request

curl -s $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members/123456 \
-X PUT -d '{"status":"accepted"}' -H "Content-Type: application/json" -H "X-Auth-Token: $AUTH_TOKEN"|python -m json.tool

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.
  • -s: Runs the command in silent mode.
  • -H: Specified header information. In this case, it provides the content-type and the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.
  • -d: Specifies the JSON request body.
  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Update an image member with cURL response

{
   "created_at": "2013-09-20T19:22:19Z",
   "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
   "member_id": "123456",
   "schema": "/v2/schemas/member",
   "status": "accepted",
   "updated_at": "2013-09-20T20:15:31Z"
}

Deleting an image member#

If you decide to no longer share your image with a user, delete that image member.

Issue the following cURL command to delete an image member for an image. In this example, you delete the user 123456 so that the user can no longer share the image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL delete an image member request

curl -i $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members/123456 \
-X DELETE \
-H "X-Auth-Token: $AUTH_TOKEN"

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.

  • -i: Includes headers in the output so you can see the result of the request.

  • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.

    If the operation is successful, it returns an HTTP 204 response code with no response body.

Previous Use images
Next General API information
Docs
  • Style Guide for Technical Content
  • Cloud Backup
  • Cloud Block Storage
  • Cloud Databases
  • Cloud DNS
  • Cloud Files
  • Identity
  • Cloud Images
  • Cloud Load Balancers
  • Cloud Monitoring
  • Cloud Orchestration
  • Cloud Networks
  • Cloud Queues
  • Cloud Servers
  • Rackspace Auto Scale
  • Rackspace CDN
Sdks
  • Go
  • Java
  • .Net
  • Node
  • PHP
  • Python
  • Ruby
Partner Tools
  • Airbrake
  • Mailgun
  • ObjectRocket
  • RedisToGo
Blog
  • Technical Blog
  • Rackspace Blog
©2019 Rackspace US, Inc.
  • ©2019 Rackspace US, Inc.
  • About Rackspace
  • Investors
  • Careers
  • Privacy Statement
  • Website Terms
  • Trademarks