1 | # MinIO JavaScript Library for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
|
2 |
|
3 | [![NPM](https://nodei.co/npm/minio.png)](https://nodei.co/npm/minio/)
|
4 |
|
5 | The MinIO JavaScript Client SDK provides simple APIs to access any Amazon S3 compatible object storage server.
|
6 |
|
7 | 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://docs.min.io/docs/javascript-client-api-reference) documentation.
|
8 |
|
9 | This document assumes that you have a working [nodejs](http://nodejs.org/) setup in place.
|
10 |
|
11 |
|
12 | ## Download from NPM
|
13 |
|
14 | ```sh
|
15 | npm install --save minio
|
16 | ```
|
17 |
|
18 | ## Download from Source
|
19 |
|
20 | ```sh
|
21 | git clone https://github.com/minio/minio-js
|
22 | cd minio-js
|
23 | npm install
|
24 | npm install -g
|
25 | ```
|
26 |
|
27 | ## Using with TypeScript
|
28 |
|
29 | ```sh
|
30 | npm install --save-dev @types/minio
|
31 | ```
|
32 |
|
33 | ## Initialize MinIO Client
|
34 |
|
35 | You need five items in order to connect to MinIO object storage server.
|
36 |
|
37 |
|
38 | | Params | Description |
|
39 | | :------- | :------------ |
|
40 | | endPoint | URL to object storage service. |
|
41 | |port| TCP/IP port number. This input is optional. Default value set to ``80`` for HTTP and ``443`` for HTTPs.|
|
42 | | accessKey | Access key is like user ID that uniquely identifies your account. |
|
43 | | secretKey | Secret key is the password to your account. |
|
44 | |useSSL |Set this value to 'true' to enable secure (HTTPS) access |
|
45 |
|
46 |
|
47 | ```js
|
48 | var Minio = require('minio')
|
49 |
|
50 | var minioClient = new Minio.Client({
|
51 | endPoint: 'play.min.io',
|
52 | port: 9000,
|
53 | useSSL: true,
|
54 | accessKey: 'Q3AM3UQ867SPQQA43P2F',
|
55 | secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
|
56 | });
|
57 | ```
|
58 |
|
59 | ## Quick Start Example - File Uploader
|
60 |
|
61 | This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket.
|
62 |
|
63 | 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.
|
64 |
|
65 | #### file-uploader.js
|
66 |
|
67 | ```js
|
68 | var Minio = require('minio')
|
69 |
|
70 | // Instantiate the minio client with the endpoint
|
71 | // and access keys as shown below.
|
72 | var minioClient = new Minio.Client({
|
73 | endPoint: 'play.min.io',
|
74 | port: 9000,
|
75 | useSSL: true,
|
76 | accessKey: 'Q3AM3UQ867SPQQA43P2F',
|
77 | secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
|
78 | });
|
79 |
|
80 | // File that needs to be uploaded.
|
81 | var file = '/tmp/photos-europe.tar'
|
82 |
|
83 | // Make a bucket called europetrip.
|
84 | minioClient.makeBucket('europetrip', 'us-east-1', function(err) {
|
85 | if (err) return console.log(err)
|
86 |
|
87 | console.log('Bucket created successfully in "us-east-1".')
|
88 |
|
89 | var metaData = {
|
90 | 'Content-Type': 'application/octet-stream',
|
91 | 'X-Amz-Meta-Testing': 1234,
|
92 | 'example': 5678
|
93 | }
|
94 | // Using fPutObject API upload your file to the bucket europetrip.
|
95 | minioClient.fPutObject('europetrip', 'photos-europe.tar', file, metaData, function(err, etag) {
|
96 | if (err) return console.log(err)
|
97 | console.log('File uploaded successfully.')
|
98 | });
|
99 | });
|
100 | ```
|
101 |
|
102 | #### Run file-uploader
|
103 |
|
104 | ```sh
|
105 | node file-uploader.js
|
106 | Bucket created successfully in "us-east-1".
|
107 |
|
108 | mc ls play/europetrip/
|
109 | [2016-05-25 23:49:50 PDT] 17MiB photos-europe.tar
|
110 | ```
|
111 |
|
112 | ## API Reference
|
113 |
|
114 | The full API Reference is available here.
|
115 |
|
116 | * [Complete API Reference](https://docs.min.io/docs/javascript-client-api-reference)
|
117 |
|
118 | ### API Reference : Bucket Operations
|
119 |
|
120 | * [`makeBucket`](https://docs.min.io/docs/javascript-client-api-reference#makeBucket)
|
121 | * [`listBuckets`](https://docs.min.io/docs/javascript-client-api-reference#listBuckets)
|
122 | * [`bucketExists`](https://docs.min.io/docs/javascript-client-api-reference#bucketExists)
|
123 | * [`removeBucket`](https://docs.min.io/docs/javascript-client-api-reference#removeBucket)
|
124 | * [`listObjects`](https://docs.min.io/docs/javascript-client-api-reference#listObjects)
|
125 | * [`listObjectsV2`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2)
|
126 | * [`listObjectsV2WithMetadata`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2WithMetadata) (Extension)
|
127 | * [`listIncompleteUploads`](https://docs.min.io/docs/javascript-client-api-reference#listIncompleteUploads)
|
128 |
|
129 | ### API Reference : File Object Operations
|
130 |
|
131 | * [`fPutObject`](https://docs.min.io/docs/javascript-client-api-reference#fPutObject)
|
132 | * [`fGetObject`](https://docs.min.io/docs/javascript-client-api-reference#fGetObject)
|
133 |
|
134 | ### API Reference : Object Operations
|
135 |
|
136 | * [`getObject`](https://docs.min.io/docs/javascript-client-api-reference#getObject)
|
137 | * [`putObject`](https://docs.min.io/docs/javascript-client-api-reference#putObject)
|
138 | * [`copyObject`](https://docs.min.io/docs/javascript-client-api-reference#copyObject)
|
139 | * [`statObject`](https://docs.min.io/docs/javascript-client-api-reference#statObject)
|
140 | * [`removeObject`](https://docs.min.io/docs/javascript-client-api-reference#removeObject)
|
141 | * [`removeObjects`](https://docs.min.io/docs/javascript-client-api-reference#removeObjects)
|
142 | * [`removeIncompleteUpload`](https://docs.min.io/docs/javascript-client-api-reference#removeIncompleteUpload)
|
143 |
|
144 | ### API Reference : Presigned Operations
|
145 |
|
146 | * [`presignedGetObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedGetObject)
|
147 | * [`presignedPutObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedPutObject)
|
148 | * [`presignedPostPolicy`](https://docs.min.io/docs/javascript-client-api-reference#presignedPostPolicy)
|
149 |
|
150 | ### API Reference : Bucket Notification Operations
|
151 |
|
152 | * [`getBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#getBucketNotification)
|
153 | * [`setBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#setBucketNotification)
|
154 | * [`removeAllBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#removeAllBucketNotification)
|
155 | * [`listenBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#listenBucketNotification) (MinIO Extension)
|
156 |
|
157 | ### API Reference : Bucket Policy Operations
|
158 |
|
159 | * [`getBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#getBucketPolicy)
|
160 | * [`setBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#setBucketPolicy)
|
161 |
|
162 |
|
163 | ## Full Examples
|
164 |
|
165 | #### Full Examples : Bucket Operations
|
166 |
|
167 | * [list-buckets.js](https://github.com/minio/minio-js/blob/master/examples/list-buckets.js)
|
168 | * [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js)
|
169 | * [list-objects-v2.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2.js)
|
170 | * [list-objects-v2-with-metadata.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2-with-metadata.js) (Extension)
|
171 | * [bucket-exists.js](https://github.com/minio/minio-js/blob/master/examples/bucket-exists.js)
|
172 | * [make-bucket.js](https://github.com/minio/minio-js/blob/master/examples/make-bucket.js)
|
173 | * [remove-bucket.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket.js)
|
174 | * [list-incomplete-uploads.js](https://github.com/minio/minio-js/blob/master/examples/list-incomplete-uploads.js)
|
175 |
|
176 | #### Full Examples : File Object Operations
|
177 | * [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js)
|
178 | * [fget-object.js](https://github.com/minio/minio-js/blob/master/examples/fget-object.js)
|
179 |
|
180 | #### Full Examples : Object Operations
|
181 | * [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js)
|
182 | * [get-object.js](https://github.com/minio/minio-js/blob/master/examples/get-object.js)
|
183 | * [copy-object.js](https://github.com/minio/minio-js/blob/master/examples/copy-object.js)
|
184 | * [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js)
|
185 | * [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js)
|
186 | * [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js)
|
187 | * [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js)
|
188 |
|
189 | #### Full Examples : Presigned Operations
|
190 | * [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js)
|
191 | * [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js)
|
192 | * [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js)
|
193 |
|
194 | #### Full Examples: Bucket Notification Operations
|
195 | * [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js)
|
196 | * [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js)
|
197 | * [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js)
|
198 | * [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (MinIO Extension)
|
199 |
|
200 | #### Full Examples: Bucket Policy Operations
|
201 | * [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js)
|
202 | * [set-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.js)
|
203 |
|
204 | ## Explore Further
|
205 | * [Complete Documentation](https://docs.min.io)
|
206 | * [MinIO JavaScript Client SDK API Reference](https://docs.min.io/docs/javascript-client-api-reference)
|
207 | * [Build your own Shopping App Example- Full Application Example ](https://github.com/minio/minio-js-store-app)
|
208 |
|
209 | ## Contribute
|
210 |
|
211 | [Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md)
|
212 |
|
213 | [![Build Status](https://travis-ci.org/minio/minio-js.svg)](https://travis-ci.org/minio/minio-js)
|
214 | [![Build status](https://ci.appveyor.com/api/projects/status/1d05e6nvxcelmrak?svg=true)](https://ci.appveyor.com/project/harshavardhana/minio-js)
|