Skip to content

Latest commit

 

History

History
373 lines (346 loc) · 8.74 KB

web-links.md

File metadata and controls

373 lines (346 loc) · 8.74 KB
Raw

Web Links

Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, so they will also support shared links, copy, permanent delete, and restore.

Create a Web Link

To create a web link call the weblinks.create(url, parentID, options, callback) method.

client.weblinks.create(
	'https://www.box.com',
	'22222',
	{
		name: 'Box Website!',
		description: 'Cloud Content Management'
	})
	.then(weblink => {
		/* weblink -> {
			type: 'web_link',
			id: '11111',
			sequence_id: '0',
			etag: '0',
			name: 'Box Website!',
			url: 'https://www.box.com',
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2015-05-07T15:00:01-07:00',
			modified_at: '2015-05-07T15:00:01-07:00',
			parent: 
			{ type: 'folder',
				id: '22222',
				sequence_id: '1',
				etag: '1',
				name: 'Bookmarks' },
			description: 'Enterprise Cloud Content Management',
			item_status: 'active',
			trashed_at: null,
			purged_at: null,
			shared_link: null,
			path_collection: 
			{ total_count: 2,
				entries: 
				[ { type: 'folder',
					id: '0',
					sequence_id: null,
					etag: null,
					name: 'All Files' },
					{ type: 'folder',
					id: '22222',
					sequence_id: '1',
					etag: '1',
					name: 'Bookmarks' } ] },
			modified_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			owned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' } }
		*/
	});

Get a Web Link's information

You can request a web link object by ID by calling weblinks.get(weblinkID, options, callback).

client.weblinks.get('11111')
	.then(weblink => {
		/* weblink -> {
			type: 'web_link',
			id: '11111',
			sequence_id: '0',
			etag: '0',
			name: 'Box Website!',
			url: 'https://www.box.com',
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2015-05-07T15:00:01-07:00',
			modified_at: '2015-05-07T15:00:01-07:00',
			parent: 
			{ type: 'folder',
				id: '22222',
				sequence_id: '1',
				etag: '1',
				name: 'Bookmarks' },
			description: 'Enterprise Cloud Content Management',
			item_status: 'active',
			trashed_at: null,
			purged_at: null,
			shared_link: null,
			path_collection: 
			{ total_count: 2,
				entries: 
				[ { type: 'folder',
					id: '0',
					sequence_id: null,
					etag: null,
					name: 'All Files' },
					{ type: 'folder',
					id: '22222',
					sequence_id: '1',
					etag: '1',
					name: 'Bookmarks' } ] },
			modified_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			owned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' } }
		*/
	});

Requesting information for only the fields you need with the fields option can improve performance and reduce the size of the network request.

client.weblinks.get('11111', {fields: 'url,name,description'})
	.then(weblink => {
		/* weblink -> {
			type: 'web_link',
			id: '11111',
			sequence_id: '0',
			etag: '0',
			name: 'Box Website!',
			url: 'https://www.box.com',
			description: 'Enterprise Cloud Content Management' }
		*/
	});

Update a Web Link

To update a web link call the weblinks.update(weblinkID, updates, callback) method with the fields to update and their new values.

client.weblinks.update(
	'11111',
	{
		name: 'Box Marketing Site',
		description: 'First page that customers land on'
	})
	.then(weblink => {
		/* weblink -> {
			type: 'web_link',
			id: '11111',
			sequence_id: '0',
			etag: '0',
			name: 'Box Marketing Site',
			url: 'https://www.box.com',
			created_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2015-05-07T15:00:01-07:00',
			modified_at: '2017-06-13T12:34:51-07:00',
			parent: 
			{ type: 'folder',
				id: '22222',
				sequence_id: '1',
				etag: '1',
				name: 'Bookmarks' },
			description: 'First page that customers land on',
			item_status: 'active',
			trashed_at: null,
			purged_at: null,
			shared_link: null,
			path_collection: 
			{ total_count: 2,
				entries: 
				[ { type: 'folder',
					id: '0',
					sequence_id: null,
					etag: null,
					name: 'All Files' },
					{ type: 'folder',
					id: '22222',
					sequence_id: '1',
					etag: '1',
					name: 'Bookmarks' } ] },
			modified_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' },
			owned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '[email protected]' } }
		*/
	});

Delete a Web Link

To move a web link to the trash call the weblinks.delete(weblinkID, callback) method.

client.weblinks.delete('11111')
	.then(() => {
		// deletion succeeded — no value returned
	});

Copy a Web Link

Call the weblinks.copy(webLinkID, destinationFolderID, options, callback) method to copy a web link into another folder.

client.weblinks.copy('11111', '0')
    .then(webLinkCopy => {
       /* webLinkCopy -> {
		    type: 'web_link',
			id: '11112',
			sequence_id: '0',
			etag: '0',
			name: 'Renamed web link copy',
			url: 'http://example.com',
			created_by:
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2019-03-26T12:49:06-07:00',
			modified_at: '2019-03-26T12:49:06-07:00',
			parent:
			{ type: 'folder',
				id: '0',
				sequence_id: null,
				etag: null,
				name: 'All Files' },
			description: '',
			item_status: 'active',
			trashed_at: null,
			purged_at: null,
			shared_link: null,
			path_collection:
			{ total_count: 1,
				entries:
				[ { type: 'folder',
					id: '0',
					sequence_id: null,
					etag: null,
					name: 'All Files' } ] },
			modified_by:
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' },
			owned_by:
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' } }
        */
    });

An optional name parameter can also be passed to rename the folder on copy. This can be used to avoid a name conflict when there is already an item with the same name in the target folder.

client.weblinks.copy('12345', '0', {name: 'Renamed web link'})
    .then(webLinkCopy => {
        // ...
    });

Move a Web Link

Call the weblinks.move(webLinkID, destinationFolderID, callback) method with the destination you want the folder moved to.

var webLinkID = '88888';
var destinationFolderID = '0';
client.weblinks.move(webLinkID, destinationFolderID)
    .then(webLink => {
       /* webLink -> {
		    type: 'web_link',
			id: '88888',
			sequence_id: '0',
			etag: '0',
			name: 'Example Web Link',
			url: 'http://example.com',
			created_by:
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' },
			created_at: '2019-03-26T12:49:06-07:00',
			modified_at: '2019-03-26T12:49:06-07:00',
			parent:
			{ type: 'folder',
				id: '0',
				sequence_id: null,
				etag: null,
				name: 'All Files' },
			description: '',
			item_status: 'active',
			trashed_at: null,
			purged_at: null,
			shared_link: null,
			path_collection:
			{ total_count: 1,
				entries:
				[ { type: 'folder',
					id: '0',
					sequence_id: null,
					etag: null,
					name: 'All Files' } ] },
			modified_by:
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' },
			owned_by:
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: '[email protected]' } }
        */
    });