Home > Blogs > VMware Developer Blog


API Tutorial – Basic Life Cycle of a Content Library

This blog post is a part of the blog series published by the Content Library team. Please find all the blog posts by the team at this link.

We discussed the requirements and how to prepare the environment to use the Content Library APIs in the Getting Started with the Content Library APIs tutorial. Now we should have an environment ready to make API calls against the Content Library Service in a vCenter Server instance. In this tutorial, we will go through the basic life cycle of a library and library items. The basic operations we will cover are:


Creating a Local Library

Creating a local library requires you to create an instance of LibraryModel and set the following fields:

  • the library name
  • the library type. There are two types of libraries:
    • LOCAL libraries. These are independent library. The content is stored locally and it can be modified.
    • SUBSCRIBED libraries. The content for these libraries is retrieved from a remote location. The owner of the subscribed library cannot make changes to it because its source of truth is elsewhere.
  • a storage backing. This is the storage that is used when the library gets created. There are two supported storage backings
    • DATASTORE for datastores. These are vCenter Server managed datastore objects, learn more about them at this link.
    • OTHER for file system based storage. This storage is mounted to the vCenter Server machine and has to be accessible to the Content Library Service process.
LibraryModel libraryModel = new LibraryModel();
libraryModel.setName("my library");
libraryModel.setType(LibraryType.LOCAL);

StorageBacking libraryBacking = new StorageBacking();
libraryBacking.setType(Type.OTHER);
libraryBacking.setStorageUri(URI.create("file:///tmp"));
libraryModel.setStorageBackings(Collections.singletonList
        (libraryBacking));

// create the library
String libraryId = client.localLibrary()
        .create(null /* client token */, libraryModel);

Updating the Library Name

This is as easy as just calling update(). There is no need to do a get() of the library data, because the update() does not modify fields not included in the LibraryModel.

libraryModel = new LibraryModel();
libraryModel.setName("new library name");
client.localLibrary().update(libraryId, libraryModel);

Adding an Item

A library item groups files within the same logical entity. This is used to represent entities that contain multiple files. A good example is an OVF item that will contain an OVF file as well as VMDK files for disks. One important aspect of items is their type. The  type of the library item may change how the Content Library Service interacts with the item. The Content Library Service differentiates between the special types and the rest of the types. The special types can be retrieved through a call to the type service. In this release, the only special type is OVF. In general we recommend that clients pick the type file if they don’t want any special handling for their uploaded files.

In this example, we create an item of the type ISO.

ItemModel item = new ItemModel();
item.setName("cdrom");
item.setLibraryId(libraryId);
item.setType("iso");
String itemId =
        client.item().create(null /* client token */, item);

Importing an Item File from a Remote URL

All content changes to library items have to go through what is called an UpdateSession. From an UpdateSession, we can either add a file by instructing the Content Library Service to pull a file from a remote URL (for example, a web server) or asking the client to push the bits from their local disk directly to the service. The former is usually the easiest option. Here is one example of uploading an ISO file from a remote URL:

UpdateSessionModel updateSessionModel = new UpdateSessionModel();
updateSessionModel.setLibraryItemId(itemId);
String sessionId =
        client.updateSession().create(null, updateSessionModel);

AddSpec file = new AddSpec();
file.setName("cdrom.iso");
file.setSourceType(SourceType.PULL);
TransferEndpoint endpoint = new TransferEndpoint();
endpoint.setUri(URI.create("http://example.com/cdrom.iso"));
file.setSourceEndpoint(endpoint);
client.updateSessionFile().add(sessionId, file);

// complete the session
client.updateSession().complete(sessionId);

In the Uploading an OVF Template to a Content Library tutorial, we go through UpdateSession APIs in more details for both uploading from the local machine and uploading from remote URL.

Deleting Items and Libraries

To delete an item

client.item().delete(itemId);

To delete a library

client.localLibrary().delete(libraryId);

Note that deleting a library will automatically delete all the items inside it.

Now we have learned how to use APIs to manage the basic lifecycle of library and library item, in the next tutorial, we explore the APIs for Uploading an OVF Template to a Content Library.

More in This Series