Update the JavaScript SDK Quickstart (#1236)

minio · Dec 19, 2023 · 46532ac · 46532ac
1 parent 0327ff8
commit 46532ac
Showing 1 changed file with 72 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -2,11 +2,12 @@
 
 [![NPM](https://nodei.co/npm/minio.png)](https://nodei.co/npm/minio/)
 
-The MinIO JavaScript Client SDK provides simple APIs to access any Amazon S3 compatible object storage server.
+The MinIO JavaScript Client SDK provides high level APIs to access any Amazon S3 compatible object storage server.
 
-This quickstart guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) documentation.
+This guide will show you how to install the client SDK and execute an example JavaScript program.
+For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html) documentation.
 
-This document assumes that you have a working [nodejs](http://nodejs.org/) setup in place.
+This document presumes you have a working [Node.js](http://nodejs.org/) development environment, LTS versions v16, v18 or v20.
 
 ## Download from NPM
 
@@ -30,15 +31,15 @@ npm install -g
 
 ## Initialize MinIO Client
 
-You need five items in order to connect to MinIO object storage server.
+The following parameters are needed to connect to a MinIO object storage server:
 
-| Params    | Description                                                                                         |
-| :-------- | :-------------------------------------------------------------------------------------------------- |
-| endPoint  | URL to object storage service.                                                                      |
-| port      | TCP/IP port number. This input is optional. Default value set to `80` for HTTP and `443` for HTTPs. |
-| accessKey | Access key is like user ID that uniquely identifies your account.                                   |
-| secretKey | Secret key is the password to your account.                                                         |
-| useSSL    | Set this value to 'true' to enable secure (HTTPS) access                                            |
+| Parameter   | Description                                                                  |
+| :---------- | :--------------------------------------------------------------------------- |
+| `endPoint`  | Hostname of the object storage service.                                      |
+| `port`      | TCP/IP port number. Optional, defaults to `80` for HTTP and `443` for HTTPs. |
+| `accessKey` | Access key (user ID) of an account in the S3 service.                        |
+| `secretKey` | Secret key (password) of an account in the S3 service.                       |
+| `useSSL`    | Optional, set to 'true' to enable secure (HTTPS) access.                     |
 
 ```js
 import * as Minio from 'minio'
@@ -54,17 +55,21 @@ const minioClient = new Minio.Client({
 
 ## Quick Start Example - File Uploader
 
-This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket.
+This example connects to an object storage server, creates a bucket, and uploads a file to the bucket.
+It uses the MinIO `play` server, a public MinIO cluster located at [https://play.min.io](https://play.min.io).
 
-We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public.
+The `play` server runs the latest stable version of MinIO and may be used for testing and development.
+The access credentials shown in this example are open to the public.
+All data uploaded to `play` should be considered public and non-protected.
 
-#### file-uploader.js
+#### file-uploader.mjs
 
 ```js
 import * as Minio from 'minio'
 
-// Instantiate the minio client with the endpoint
-// and access keys as shown below.
+// Instantiate the MinIO client with the object store service
+// endpoint and an authorized user's credentials
+// play.min.io is the MinIO public test cluster
 const minioClient = new Minio.Client({
   endPoint: 'play.min.io',
   port: 9000,
@@ -73,40 +78,61 @@ const minioClient = new Minio.Client({
   secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
 })
 
-// File that needs to be uploaded.
-const file = '/tmp/photos-europe.tar'
+// File to upload
+const sourceFile = '/tmp/test-file.txt'
 
-// Make a bucket called europetrip.
-await minioClient.makeBucket('europetrip', 'us-east-1')
-console.log('Bucket created successfully in "us-east-1".')
+// Destination bucket
+const bucket = 'js-test-bucket'
 
+// Destination object name
+const destinationObject = 'my-test-file.txt'
+
+// Check if the bucket exists
+// If it doesn't, create it
+const exists = await minioClient.bucketExists(bucket)
+if (exists) {
+  console.log('Bucket ' + bucket + ' exists.')
+} else {
+  await minioClient.makeBucket(bucket, 'us-east-1')
+  console.log('Bucket ' + bucket + ' created in "us-east-1".')
+}
+
+// Set the object metadata
 var metaData = {
-  'Content-Type': 'application/octet-stream',
+  'Content-Type': 'text/plain',
   'X-Amz-Meta-Testing': 1234,
   example: 5678,
 }
-// Using fPutObject API upload your file to the bucket europetrip.
-await minioClient.fPutObject('europetrip', 'photos-europe.tar', file, metaData)
-console.log('File uploaded successfully.')
+
+// Upload the file with fPutObject
+// If an object with the same name exists,
+// it is updated with new data
+await minioClient.fPutObject(bucket, destinationObject, sourceFile, metaData)
+console.log('File ' + sourceFile + ' uploaded as object ' + destinationObject + ' in bucket ' + bucket)
 ```
 
-#### Run file-uploader
+#### Run the File Uploader
 
 ```sh
-node file-uploader.js
-Bucket created successfully in "us-east-1".
+node file-uploader.mjs
+Bucket js-test-bucket created successfully in "us-east-1".
+File /tmp/test-file.txt uploaded successfully as my-test-file.txt to bucket js-test-bucket
+```
+
+Verify the object was created with [`mc`](https://min.io/docs/minio/linux/reference/minio-mc.html):
 
-mc ls play/europetrip/
-[2016-05-25 23:49:50 PDT]  17MiB photos-europe.tar
+```
+mc ls play/js-test-bucket
+[2023-11-10 17:52:20 UTC]  20KiB STANDARD my-test-file.txt
 ```
 
 ## API Reference
 
-The full API Reference is available here.
+The complete API Reference is available here:
 
-- [Complete API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html)
+- [MinIO JavaScript API Reference](https://min.io/docs/minio/linux/developers/javascript/API.html)
 
-### API Reference : Bucket Operations
+### Bucket Operations
 
 - [`makeBucket`](https://min.io/docs/minio/linux/developers/javascript/API.html#makeBucket)
 - [`listBuckets`](https://min.io/docs/minio/linux/developers/javascript/API.html#listBuckets)
@@ -124,12 +150,12 @@ The full API Reference is available here.
 - [`getObjectLockConfig`](https://min.io/docs/minio/linux/developers/javascript/API.html#getObjectLockConfig)
 - [`setObjectLockConfig`](https://min.io/docs/minio/linux/developers/javascript/API.html#setObjectLockConfig)
 
-### API Reference : File Object Operations
+### File Object Operations
 
 - [`fPutObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#fPutObject)
 - [`fGetObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#fGetObject)
 
-### API Reference : Object Operations
+### Object Operations
 
 - [`getObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#getObject)
 - [`putObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#putObject)
@@ -140,27 +166,27 @@ The full API Reference is available here.
 - [`removeIncompleteUpload`](https://min.io/docs/minio/linux/developers/javascript/API.html#removeIncompleteUpload)
 - [`selectObjectContent`](https://min.io/docs/minio/linux/developers/javascript/API.html#selectObjectContent)
 
-### API Reference : Presigned Operations
+### Presigned Operations
 
 - [`presignedGetObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#presignedGetObject)
 - [`presignedPutObject`](https://min.io/docs/minio/linux/developers/javascript/API.html#presignedPutObject)
 - [`presignedPostPolicy`](https://min.io/docs/minio/linux/developers/javascript/API.html#presignedPostPolicy)
 
-### API Reference : Bucket Notification Operations
+### Bucket Notification Operations
 
 - [`getBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#getBucketNotification)
 - [`setBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#setBucketNotification)
 - [`removeAllBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#removeAllBucketNotification)
 - [`listenBucketNotification`](https://min.io/docs/minio/linux/developers/javascript/API.html#listenBucketNotification) (MinIO Extension)
 
-### API Reference : Bucket Policy Operations
+### Bucket Policy Operations
 
 - [`getBucketPolicy`](https://min.io/docs/minio/linux/developers/javascript/API.html#getBucketPolicy)
 - [`setBucketPolicy`](https://min.io/docs/minio/linux/developers/javascript/API.html#setBucketPolicy)
 
-## Full Examples
+## Examples
 
-#### Full Examples : Bucket Operations
+#### Bucket Operations
 
 - [list-buckets.mjs](https://github.com/minio/minio-js/blob/master/examples/list-buckets.mjs)
 - [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js)
@@ -184,12 +210,12 @@ The full API Reference is available here.
 - [get-bucket-replication.mjs](https://github.com/minio/minio-js/blob/master/examples/get-bucket-replication.mjs)
 - [remove-bucket-replication.mjs](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-replication.mjs)
 
-#### Full Examples : File Object Operations
+#### File Object Operations
 
 - [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js)
 - [fget-object.mjs](https://github.com/minio/minio-js/blob/master/examples/fget-object.mjs)
 
-#### Full Examples : Object Operations
+#### Object Operations
 
 - [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js)
 - [get-object.mjs](https://github.com/minio/minio-js/blob/master/examples/get-object.mjs)
@@ -208,20 +234,20 @@ The full API Reference is available here.
 - [compose-object.js](https://github.com/minio/minio-js/blob/master/examples/compose-object.js)
 - [select-object-content.js](https://github.com/minio/minio-js/blob/master/examples/select-object-content.js)
 
-#### Full Examples : Presigned Operations
+#### Presigned Operations
 
 - [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js)
 - [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js)
 - [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js)
 
-#### Full Examples: Bucket Notification Operations
+#### Bucket Notification Operations
 
 - [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js)
 - [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js)
 - [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js)
 - [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (MinIO Extension)
 
-#### Full Examples: Bucket Policy Operations
+#### Bucket Policy Operations
 
 - [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js)
 - [set-bucket-policy.mjs](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.mjs)
@@ -237,6 +263,6 @@ The full API Reference is available here.
 
 ## Contribute
 
-[Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md)
+- [Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md)
 
 ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/minio/minio-js/nodejs.yml)