From 83f5536e0a258dbd367dcb1b5de4764b5ea963fc Mon Sep 17 00:00:00 2001 From: Jason Yang Date: Wed, 12 Sep 2018 17:29:21 -0400 Subject: [PATCH 1/6] WIP: Editing rackspace DNS doc --- docs/providers/rackspace/dns.md | 198 +------------------------------- 1 file changed, 6 insertions(+), 192 deletions(-) diff --git a/docs/providers/rackspace/dns.md b/docs/providers/rackspace/dns.md index 255be6f2b..5dbb191b2 100644 --- a/docs/providers/rackspace/dns.md +++ b/docs/providers/rackspace/dns.md @@ -130,196 +130,10 @@ client.createZones([{ }) ``` -#### client.destroyContainer(container, function(err, result) { }) - -Removes the [`container`](#container-model) from the storage account. If there are any files within the `container`, they will be deleted before removing the `container` on the client. `result` will be `true` on success. - -#### client.updateContainerMetadata(container, function(err, container) { }) - -Updates the metadata on the provided [`container`](#container-model) . Currently, the `updateContainer` method only adds new metadata fields. If you need to remove specific metadata properties, you should call `client.removeContainerMetadata(...)`. - -```javascript -container.metadata.color = 'red'; -client.updateContainerMetadata(container, function(err, container) { - // ... -}) -``` - -#### client.removeContainerMetadata(container, metadataToRemove, function(err, container) { }) - -Removes the keys in the `metadataToRemove` object from the stored [`container`](#container-model) metadata. - -```Javascript -client.removeContainerMetadata(container, { year: false }, function(err, c) { - // ... -}); -``` - -### File APIs - -* [`client.upload(options, function(err, result) { })`](#clientuploadoptions-functionerr-result--) -* [`client.download(options, function(err, file) { })`](#clientdownloadoptions-functionerr-file--) -* [`client.getFile(container, file, function(err, file) { })`](#clientgetfilecontainer-file-functionerr-file--) -* [`client.getFiles(container, function(err, file) { })`](#clientgetfilescontainer-functionerr-file--) -* [`client.removeFile(container, file, function(err, result) { })`](#clientremovefilecontainer-file-functionerr-result--) -* [`client.updateFileMetadata(container, file, function(err, file) { })`](#clientupdatefilemetadatacontainer-file-functionerr-file--) - -### File API Details - -For all of the file methods, you can pass either an instance of [`container`](#container-model) or the container name as `container`. For example: - -```Javascript -client.getFile('my-container', 'my-file', function(err, file) { ... }); -``` - -This call is functionally equivalent to: - -```Javascript -var myContainer = new Container({ name: 'my-container' }); - -client.getFile(myContainer, 'my-file', function(err, file) { ... }); -``` - -#### client.upload(options, function(err, result) { }) - -Returns a writeable stream. Upload a new file to a [`container`](#container-model). `result` will be `true` on success. - -To upload a file, you need to provide an `options` argument: - -```Javascript -var options = { - // required options - container: 'my-container', // this can be either the name or an instance of container - remote: 'my-file', // name of the new file - - // optional, either stream or local - stream: myStream, // any instance of a readable stream - local: '/path/to/local/file' // a path to any local file - - // Other optional values - metadata: { // provide any number of property/values for metadata - campaign: '2012 magazine' - }, - headers: { // optionally provide raw headers to send to cloud files - 'content-type': 'application/json' - } -}; -``` - -You need not provide either `stream` or `local`. `client.upload` returns a writeable stream, so you can simply pipe directly into it from your stream. For example: - -```Javascript -var fs = require('fs'), - pkgcloud = require('pkgcloud'); - -var client = pkgcloud.providers.rackspace.storage.createClient({ ... }); - -var myFile = fs.createReadStream('/my/local/file'); - -myFile.pipe(client.upload({ - container: 'my-container', - remote: 'my-file' -}, function(err, result) { - // handle the upload result -})); -``` - -You could also upload a local file via the `local` property on `options`: - -```Javascript -var pkgcloud = require('pkgcloud'); - -var client = pkgcloud.providers.rackspace.storage.createClient({ ... }); - -client.upload({ - container: 'my-container', - remote: 'my-file', - local: '/path/to/my/file' -}, function(err, result) { - // handle the upload result -}); -``` - -This is functionally equivalent to piping from an `fs.createReadStream`, but has a simplified calling convention. - -#### client.download(options, function(err, file) { }) - -Returns a readable stream. Download a [`file`](#file-model) from a [`container`](#container-model). - -To download a file, you need to provide an `options` argument: - -```Javascript -var options = { - // required options - container: 'my-container', // this can be either the name or an instance of container - remote: 'my-file', // name of the new file - - // optional, either stream or local - stream: myStream, // any instance of a writeable stream - local: '/path/to/local/file' // the path to a local file to write to -}; -``` - -You need not provide either `stream` or `local`. `client.download` returns a readable stream, so you can simply pipe it into your writeable stream. For example: - -```Javascript -var fs = require('fs'), - pkgcloud = require('pkgcloud'); - -var client = pkgcloud.providers.rackspace.storage.createClient({ ... }); - -var myFile = fs.createWriteStream('/my/local/file'); - -client.download({ - container: 'my-container', - remote: 'my-file' -}, function(err, result) { - // handle the download result -})).pipe(myFile); -``` - -You could also download to a local file via the `local` property on `options`: - -```Javascript -var pkgcloud = require('pkgcloud'); - -var client = pkgcloud.providers.rackspace.storage.createClient({ ... }); - -client.download({ - container: 'my-container', - remote: 'my-file', - local: '/path/to/my/file' -}, function(err, result) { - // handle the download result -}); -``` - -This is functionally equivalent to piping from an `fs.createWriteStream`, but has a simplified calling convention. - -#### client.getFile(container, file, function(err, file) { }) - -Retrieves the specified [`file`](#file-model) details in the specified [`container`](#container-model) from the current client instance. - -#### client.getFiles(container, function(err, files) { }) - -Retreives an array of [`file`](#file-model) for the provided [`container`](#container-model). - -#### client.removeFile(container, file, function(err, result) { }) - -Removes the provided [`file`](#file-model) from the provided [`container`](#container-model). - -#### client.updateFileMetadata(container, file, function(err, file) { }) - -Updates the [`file`](#file-model) metadata in the the provided [`container`](#container-model). - -File metadata is completely replaced with each callt o updateFileMetadata. This is different than container metadata. To delete a property, just remove it from the metadata attribute on the `File` and call `updateFileMetadata`. -```javascript -file.metadata = { - campaign = '2011 website' -}; - -client.updateFileMetadata(file.container, file, function(err, file) { - // ... -}); -``` +### Record APIs +* [`client.getRecords(zone, function (err, records) { })`](#clientgetrecordszone-functionerr-records--) +* [`client.getRecord(zone, function (err, records) { })`](#clientgetrecordzone-functionerr-record--) +* [`client.createRecord(zone, function (err, records) { })`](#clientcreaterecordzone-functionerr-record--) +* [`client.updateRecord(zone, function (err, records) { })`](#clientupdaterecordzone-functionerr-record--) +* [`client.updateRecord(zone, function (err, records) { })`](#clientdeleterecordzone-functionerr-record--) From 0c2cdfe5d7f51dfd34ed3a06213a79053b8b72d3 Mon Sep 17 00:00:00 2001 From: Jason Yang Date: Wed, 19 Sep 2018 12:44:01 -0400 Subject: [PATCH 2/6] WIP: Add in Records API references --- docs/providers/rackspace/dns.md | 80 ++++++++++++++++++++++++++++++--- 1 file changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/providers/rackspace/dns.md b/docs/providers/rackspace/dns.md index 5dbb191b2..30d6bcd86 100644 --- a/docs/providers/rackspace/dns.md +++ b/docs/providers/rackspace/dns.md @@ -87,7 +87,7 @@ client.getZone(12345678, function(err, zone) { ... }); This call is functionally equivalent to: ```Javascript -var myZone = new Zone({ id: 12345 }); +const myZone = new Zone({ id: 12345 }); client.getZone(myZone, function(err, zone) { ... }); ``` @@ -133,7 +133,77 @@ client.createZones([{ ### Record APIs * [`client.getRecords(zone, function (err, records) { })`](#clientgetrecordszone-functionerr-records--) -* [`client.getRecord(zone, function (err, records) { })`](#clientgetrecordzone-functionerr-record--) -* [`client.createRecord(zone, function (err, records) { })`](#clientcreaterecordzone-functionerr-record--) -* [`client.updateRecord(zone, function (err, records) { })`](#clientupdaterecordzone-functionerr-record--) -* [`client.updateRecord(zone, function (err, records) { })`](#clientdeleterecordzone-functionerr-record--) +* [`client.getRecord(zone, record, function (err, record) { })`](#clientgetrecordzone-functionerr-record--) +* [`client.createRecord(zone, record, function (err, record) { })`](#clientcreaterecordzone-functionerr-record--) +* [`client.updateRecord(zone, record, function (err, record) { })`](#clientupdaterecordzone-functionerr-record--) +* [`client.deleteRecord(zone, record, function (err) { })`](#clientdeleterecordzone-functionerr-record--) + +### Record API Details + +For all of the record methods that require a zone or record, you can pass either an instance of a [`zone`](#zone-model)/[`record`](#record-model) or the zone/record id as `zone`/`record`. For example: + +```Javascript +client.getRecord(12345678, 'NS-14336511' function(err, records) { ... }); +``` + +This call is functionally equivalent to: + +```Javascript +const myZone = new Zone({ id: 12345 }); +const myRecord = new Record({ id: 'NS-14336511' }); + +client.getRecord(myZone, myRecord, function(err, record) { ... }); +``` + +### client.getRecords(zone, function (err, records) { }) + +Retrieves the records for a given zone and client instance as an array of [`record`](#record-model). + +### client.getRecord(zone, record, function (err, record) { }) + +Retrives the specified [`record`](#record-model) from the specified zone and current client instance. + +### client.createRecord(zone, record, function(err, record) { }) + +Creates a new [`record`](#record-model) with attributes from the argument of `record`: + +```javascript +client.createRecord( + zone, + { + name: 'example.org', // required + type: 'example type', // required + data: '123.45.678.912', // required + ttl: 300 // optional + }, function(err, zone) { + // ... + }) +``` + +### client.updateRecord(zone, record, function(err, record) { }) + +Updates a new [`record`](#record-model) with attributes from the argument of `record`: + +```javascript +client.updateRecord( + zone, + { + id: 'NS-14336511' + // updated record attributes + }, function(err, zone) { + // ... + }) +``` + +### client.deleteRecord(zone, record, function(err, record) { }) + +Deletes the specified [`record`](#record-model) from the specified zone and current client instance. + +```javascript +client.deleteRecord( + zone, + record, + function(err, zone) { + // ... + }) +``` \ No newline at end of file From 1d895296ecc6f1e2a5dcbe6ee2317e85eebd6530 Mon Sep 17 00:00:00 2001 From: Jason Yang Date: Wed, 19 Sep 2018 12:48:46 -0400 Subject: [PATCH 3/6] WIP: Edit formatting and typos --- docs/providers/rackspace/dns.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/providers/rackspace/dns.md b/docs/providers/rackspace/dns.md index 30d6bcd86..ccf00c63c 100644 --- a/docs/providers/rackspace/dns.md +++ b/docs/providers/rackspace/dns.md @@ -136,7 +136,7 @@ client.createZones([{ * [`client.getRecord(zone, record, function (err, record) { })`](#clientgetrecordzone-functionerr-record--) * [`client.createRecord(zone, record, function (err, record) { })`](#clientcreaterecordzone-functionerr-record--) * [`client.updateRecord(zone, record, function (err, record) { })`](#clientupdaterecordzone-functionerr-record--) -* [`client.deleteRecord(zone, record, function (err) { })`](#clientdeleterecordzone-functionerr-record--) +* [`client.deleteRecord(zone, record, function (err, record) { })`](#clientdeleterecordzone-functionerr-record--) ### Record API Details @@ -155,15 +155,15 @@ const myRecord = new Record({ id: 'NS-14336511' }); client.getRecord(myZone, myRecord, function(err, record) { ... }); ``` -### client.getRecords(zone, function (err, records) { }) +#### client.getRecords(zone, function (err, records) { }) Retrieves the records for a given zone and client instance as an array of [`record`](#record-model). -### client.getRecord(zone, record, function (err, record) { }) +#### client.getRecord(zone, record, function (err, record) { }) Retrives the specified [`record`](#record-model) from the specified zone and current client instance. -### client.createRecord(zone, record, function(err, record) { }) +#### client.createRecord(zone, record, function(err, record) { }) Creates a new [`record`](#record-model) with attributes from the argument of `record`: @@ -180,7 +180,7 @@ client.createRecord( }) ``` -### client.updateRecord(zone, record, function(err, record) { }) +#### client.updateRecord(zone, record, function(err, record) { }) Updates a new [`record`](#record-model) with attributes from the argument of `record`: @@ -195,7 +195,7 @@ client.updateRecord( }) ``` -### client.deleteRecord(zone, record, function(err, record) { }) +#### client.deleteRecord(zone, record, function(err, record) { }) Deletes the specified [`record`](#record-model) from the specified zone and current client instance. From 6f42535748cf85c563e807a76a423dd7564b3fc8 Mon Sep 17 00:00:00 2001 From: Jason Yang Date: Wed, 19 Sep 2018 12:58:15 -0400 Subject: [PATCH 4/6] WIP: Fix doc links --- docs/providers/rackspace/dns.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/providers/rackspace/dns.md b/docs/providers/rackspace/dns.md index ccf00c63c..5ddf815a6 100644 --- a/docs/providers/rackspace/dns.md +++ b/docs/providers/rackspace/dns.md @@ -132,11 +132,11 @@ client.createZones([{ ### Record APIs -* [`client.getRecords(zone, function (err, records) { })`](#clientgetrecordszone-functionerr-records--) -* [`client.getRecord(zone, record, function (err, record) { })`](#clientgetrecordzone-functionerr-record--) -* [`client.createRecord(zone, record, function (err, record) { })`](#clientcreaterecordzone-functionerr-record--) -* [`client.updateRecord(zone, record, function (err, record) { })`](#clientupdaterecordzone-functionerr-record--) -* [`client.deleteRecord(zone, record, function (err, record) { })`](#clientdeleterecordzone-functionerr-record--) +* [`client.getRecords(zone, function(err, records) { })`](#clientgetrecordszone-functionerr-records--) +* [`client.getRecord(zone, record, function(err, record) { })`](#clientgetrecordzone-record-functionerr-record--) +* [`client.createRecord(zone, record, function(err, record) { })`](#clientcreaterecordzone-record-functionerr-record--) +* [`client.updateRecord(zone, record, function(err, record) { })`](#clientupdaterecordzone-record-functionerr-record--) +* [`client.deleteRecord(zone, record, function(err, record) { })`](#clientdeleterecordzone-record-functionerr-record--) ### Record API Details @@ -155,11 +155,11 @@ const myRecord = new Record({ id: 'NS-14336511' }); client.getRecord(myZone, myRecord, function(err, record) { ... }); ``` -#### client.getRecords(zone, function (err, records) { }) +#### client.getRecords(zone, function(err, records) { }) Retrieves the records for a given zone and client instance as an array of [`record`](#record-model). -#### client.getRecord(zone, record, function (err, record) { }) +#### client.getRecord(zone, record, function(err, record) { }) Retrives the specified [`record`](#record-model) from the specified zone and current client instance. From 0fa8b35ac3117fdeb692eea38388a9145b9b70b4 Mon Sep 17 00:00:00 2001 From: Jason Yang Date: Wed, 19 Sep 2018 13:13:49 -0400 Subject: [PATCH 5/6] WIP: Add in remaining Record API referneces --- docs/providers/rackspace/dns.md | 54 +++++++++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/docs/providers/rackspace/dns.md b/docs/providers/rackspace/dns.md index 5ddf815a6..e620cd000 100644 --- a/docs/providers/rackspace/dns.md +++ b/docs/providers/rackspace/dns.md @@ -135,8 +135,11 @@ client.createZones([{ * [`client.getRecords(zone, function(err, records) { })`](#clientgetrecordszone-functionerr-records--) * [`client.getRecord(zone, record, function(err, record) { })`](#clientgetrecordzone-record-functionerr-record--) * [`client.createRecord(zone, record, function(err, record) { })`](#clientcreaterecordzone-record-functionerr-record--) +* [`client.createRecords(zone, records, function(err, records) { })`](#clientcreaterecordszone-records-functionerr-records--) * [`client.updateRecord(zone, record, function(err, record) { })`](#clientupdaterecordzone-record-functionerr-record--) +* [`client.updateRecords(zone, records, function(err, records) { })`](#clientupdaterecordszone-records-functionerr-records--) * [`client.deleteRecord(zone, record, function(err, record) { })`](#clientdeleterecordzone-record-functionerr-record--) +* [`client.deleteRecords(zone, records, function(err, records) { })`](#clientdeleterecordszone-records-functionerr-records--) ### Record API Details @@ -175,7 +178,24 @@ client.createRecord( type: 'example type', // required data: '123.45.678.912', // required ttl: 300 // optional - }, function(err, zone) { + }, function(err, record) { + // ... + }) +``` + +#### client.createRecords(zone, records, function(err, records) { }) + +Batch creates multiple [`records`](#record-model) from any array of `records`. Each record should have the same properties as referenced in `createRecord`. + +```javascript +client.createRecords( + zone, + [{ + name: 'example.org', // required + type: 'example type', // required + data: '123.45.678.912', // required + ttl: 300 // optional + }], function(err, records) { // ... }) ``` @@ -190,7 +210,22 @@ client.updateRecord( { id: 'NS-14336511' // updated record attributes - }, function(err, zone) { + }, function(err, record) { + // ... + }) +``` + +#### client.updateRecords(zone, records, function(err, records) { }) + +Batch updates multiple [`records`](#record-model) from any array of `records`. Each record should have the same properties as referenced in `updateRecord`. + +```javascript +client.updateRecords( + zone, + [{ + id: 'NS-14336511' + // updated record attributes + }], function(err, records) { // ... }) ``` @@ -203,7 +238,20 @@ Deletes the specified [`record`](#record-model) from the specified zone and curr client.deleteRecord( zone, record, - function(err, zone) { + function(err, record) { + // ... + }) +``` + +#### client.deleteRecords(zone, records, function(err, records) { }) + +Batch deletes multiple [`records`](#record-model) from any array of `records`. Each record should have the same properties as referenced in `deleteRecord`. + +```javascript +client.deleteRecords( + zone, + [record], + function(err, records) { // ... }) ``` \ No newline at end of file From e4c4185c42533f845f3bf776b258f046927bc7f3 Mon Sep 17 00:00:00 2001 From: Jason Yang Date: Wed, 19 Sep 2018 13:22:25 -0400 Subject: [PATCH 6/6] [dns][docs] Update Rackspace DNS Docs --- docs/providers/rackspace/dns.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/providers/rackspace/dns.md b/docs/providers/rackspace/dns.md index e620cd000..2166ea588 100644 --- a/docs/providers/rackspace/dns.md +++ b/docs/providers/rackspace/dns.md @@ -146,14 +146,14 @@ client.createZones([{ For all of the record methods that require a zone or record, you can pass either an instance of a [`zone`](#zone-model)/[`record`](#record-model) or the zone/record id as `zone`/`record`. For example: ```Javascript -client.getRecord(12345678, 'NS-14336511' function(err, records) { ... }); +client.getRecord(12345678, 'NS-12345678' function(err, records) { ... }); ``` This call is functionally equivalent to: ```Javascript -const myZone = new Zone({ id: 12345 }); -const myRecord = new Record({ id: 'NS-14336511' }); +const myZone = new Zone({ id: 12345678 }); +const myRecord = new Record({ id: 'NS-12345678' }); client.getRecord(myZone, myRecord, function(err, record) { ... }); ``` @@ -202,13 +202,13 @@ client.createRecords( #### client.updateRecord(zone, record, function(err, record) { }) -Updates a new [`record`](#record-model) with attributes from the argument of `record`: +Updates the specified [`record`](#record-model) with attributes from the argument of `record`: ```javascript client.updateRecord( zone, { - id: 'NS-14336511' + id: 'NS-12345678' // updated record attributes }, function(err, record) { // ... @@ -223,7 +223,7 @@ Batch updates multiple [`records`](#record-model) from any array of `records`. E client.updateRecords( zone, [{ - id: 'NS-14336511' + id: 'NS-12345678' // updated record attributes }], function(err, records) { // ...