|
1 | 1 |  |
2 | 2 |
|
3 | | -# Node.js Connect |
4 | | - |
5 | | -[](https://www.npmjs.org/package/sphere-node-connect) |
6 | | - |
7 | | -[](http://travis-ci.org/sphereio/sphere-node-connect) [](http://badge.fury.io/js/sphere-node-connect) [](https://coveralls.io/r/sphereio/sphere-node-connect?branch=master) [](https://david-dm.org/sphereio/sphere-node-connect) [](https://david-dm.org/sphereio/sphere-node-connect#info=devDependencies) |
8 | | - |
9 | | -Quick and easy way to connect your Node.js app with [SPHERE.IO](http://sphere.io) HTTP APIs. |
10 | | - |
11 | | -## Table of Contents |
12 | | -* [Getting Started](#getting-started) |
13 | | -* [Documentation](#documentation) |
14 | | - * [OAuth2](#oauth2) |
15 | | - * [Rest](#rest) |
16 | | - * [Paged requests](#paged-requests) |
17 | | - * [Error handling](#error-handling) |
18 | | -* [Examples](#examples) |
19 | | -* [Contributing](#contributing) |
20 | | -* [Releasing](#releasing) |
21 | | -* [Styleguide](#styleguide) |
22 | | -* [License](#license) |
23 | | - |
24 | | - |
25 | | -## Getting Started |
26 | | -Install the module with: `npm install sphere-node-connect` |
27 | | - |
28 | | -```coffeescript |
29 | | -sphere_connect = require 'sphere-node-connect' |
30 | | -# handles OAuth2 request to retrieve an access_token |
31 | | -OAuth2 = sphere_connect.OAuth2 |
32 | | -# handles requests to HTTP APIs |
33 | | -Rest = sphere_connect.Rest |
34 | | - |
35 | | -# or simpler |
36 | | -{OAuth2, Rest} = require 'sphere-node-connect' |
37 | | -``` |
38 | | - |
39 | | -## Documentation |
40 | | -The connector exposes 2 objects: `OAuth2` and `Rest`. |
41 | | - |
42 | | -### OAuth2 |
43 | | - |
44 | | -The `OAuth2` is used to retrieve an `access_token` |
45 | | - |
46 | | -```coffeescript |
47 | | -oa = new OAuth2 |
48 | | - config: |
49 | | - client_id: '' |
50 | | - client_secret: '' |
51 | | - project_key: '' |
52 | | - host: 'auth.sphere.io' # optional |
53 | | - accessTokenUrl: '/oauth/token' # optional |
54 | | - timeout: 20000 # optional |
55 | | - rejectUnauthorized: true # optional |
56 | | - logConfig: {} # optional (see `Logging` section) |
57 | | - |
58 | | -oa.getAccessToken (error, response, body) -> # do something |
59 | | -``` |
60 | | - |
61 | | -### Rest |
62 | | - |
63 | | -The `Rest` is used to comunicate with the HTTP API. |
64 | | - |
65 | | -```coffeescript |
66 | | -rest = new Rest |
67 | | - config: |
68 | | - client_id: '' |
69 | | - client_secret: '' |
70 | | - project_key: '' |
71 | | - host: 'api.sphere.io' # optional |
72 | | - access_token: '' # optional (if not provided it will automatically retrieve an `access_token`) |
73 | | - timeout: 20000 # optional |
74 | | - rejectUnauthorized: true # optional |
75 | | - oauth_host: 'auth.sphere.io' # optional (used when retrieving the `access_token` internally) |
76 | | - user_agent: 'my client v0.1' # optional |
77 | | - logConfig: {} # optional (see `Logging` section) |
78 | | - |
79 | | -rest.GET resource, (error, response, body) -> # do something |
80 | | -rest.POST resource, payload, (error, response, body) -> # do something |
81 | | -rest.DELETE resource, (error, response, body) -> # do something |
82 | | -rest.PAGEd resource, (error, response, body) -> # (see `Paged requests` section) |
83 | | -``` |
84 | | - |
85 | | -> The `Rest` object, when instantiated, has an internal instance of the `OAuth` module accessible with `rest._oauth`. This is mainly used internally to automatically retrieve an `access_token`. |
86 | | -
|
87 | | -Currently `GET`, `POST` and `DELETE` are supported. |
88 | | - |
89 | | -#### Paged requests |
90 | | -Paged results (when querying an endpoint) can be processed in chunks, to avoid the server to return big amount of data all together. |
91 | | -The `PAGED` function recursively accumulates the paged results, returning all of them at once. |
92 | | - |
93 | | -> Use this function to safely query all results (=> `limit=0`) |
94 | | -
|
95 | | -```coffeescript |
96 | | -rest = new Rest options |
97 | | - |
98 | | -rest.PAGED '/products', (error, response, body) -> |
99 | | - # do something |
100 | | -``` |
101 | | - |
102 | | -> Note that by using this function, the `limit` is considered to be 0, meaning all results are queried. So given `limit` and `offset` parameters will be ignored. |
103 | | -
|
104 | | -```coffeescript |
105 | | -# with query params |
106 | | -rest = new Rest options |
107 | | - |
108 | | -rest.PAGED '/products?where=name%3D%22Foo%22&staged=true', (error, response, body) -> |
109 | | - # do something |
110 | | -``` |
111 | | - |
112 | | -You can also subscribe to **progress notifications** |
113 | | - |
114 | | -```coffeescript |
115 | | -rest = new Rest options |
116 | | - |
117 | | -rest.PAGED '/products', (error, response, body) -> |
118 | | - # do something |
119 | | -, (progress) -> |
120 | | - # progress is an object containing the current progress percentage |
121 | | - # and the value of the current results (array) |
122 | | - # {percentage: 20, value: [r1, r2, r3, ...]} |
123 | | -``` |
124 | | - |
125 | | -### Error handling |
126 | | -Since the connector is basically a wrapper of the [`request`](https://github.com/mikeal/request#requestoptions-callback) HTTP Client, the `callback` function comes directly from there, meaning that the 3 arguments are the same: |
127 | | - |
128 | | -- `error`: an error object when applicable (usually from [`http.ClientRequest`](http://nodejs.org/api/http.html#http_class_http_clientrequest) object) otherwise `null` |
129 | | -- `response`: an [`http.IncomingMessage`](http://nodejs.org/api/http.html#http_http_incomingmessage) object containing all kind of information about the request / response |
130 | | -- `body`: a JSON object (automatically parsed) |
131 | | - |
132 | | -As the SPHERE.IO [HTTP API](http://commercetools.de/dev/http-api.html) returns JSON responses either with resources or [error messages](http://commercetools.de/dev/http-api-projects-errors.html), the application should check the response `statusCode` and decide what to do. |
133 | | -It's always a good practice to check first for the existence of an `error` object in case there was a problem with the http client request. |
134 | | - |
135 | | -```coffeescript |
136 | | -(error, response, body) -> |
137 | | - if error |
138 | | - # do something |
139 | | - else |
140 | | - if response.statusCode is 200 |
141 | | - # ok |
142 | | - else |
143 | | - # do something else |
144 | | -``` |
145 | | - |
146 | | -### Logging |
147 | | - |
148 | | -See [`sphere-node-utils`](https://github.com/sphereio/sphere-node-utils) |
149 | | - |
150 | | - |
151 | | -## Examples |
152 | | - |
153 | | -```coffeescript |
154 | | -oa.getAccessToken (error, response, body) -> |
155 | | - if response.statusCode is 200 |
156 | | - access_token = body.access_token |
157 | | - else |
158 | | - throw new Error 'Failed to get Access Token.' |
159 | | -``` |
160 | | - |
161 | | -```coffeescript |
162 | | -# Get a list of all products |
163 | | -rest.GET '/products', (error, response, body) -> console.log(body) |
164 | | - |
165 | | -# Create a new product |
166 | | -rest.POST '/products', |
167 | | - name: { en: 'Foo' } |
168 | | - slug: { en: 'foo' } |
169 | | - productType: { id: '123', typeId: 'product-type' } |
170 | | -, (error, response, body) -> console.log(body) |
171 | | - |
172 | | -# Update a product |
173 | | -rest.POST '/products/123', |
174 | | - version: 1 |
175 | | - actions: [ |
176 | | - { action: 'changeName', name: { en: 'Boo' } } |
177 | | - ] |
178 | | -, (error, response, body) -> console.log(body) |
179 | | - |
180 | | -# Delete a product |
181 | | -rest.DELETE '/product/abc?version=3', (error, response, body) -> |
182 | | - if response.statusCode is 200 |
183 | | - console.log 'Product successfully deleted.' |
184 | | - else if response.statusCode is 404 |
185 | | - console.log 'Product does not exist.' |
186 | | - else if response.statusCode == 400 |
187 | | - console.log 'Product version does not match.' |
188 | | -``` |
189 | | - |
190 | | -## Contributing |
191 | | -In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [Grunt](http://gruntjs.com/). |
192 | | - |
193 | | -Define your SPHERE.IO credentials into a `config.js`. Since the tests run against 2 projects on different environments you need to provide the credentials for both. If you just have one project You can provide the same credentials for both. |
194 | | - |
195 | | -```javascript |
196 | | -/* SPHERE.IO credentials */ |
197 | | -exports.config = { |
198 | | - staging: { |
199 | | - client_id: "", |
200 | | - client_secret: "", |
201 | | - project_key: "", |
202 | | - oauth_host: "auth.sphere.io", |
203 | | - api_host: "api.sphere.io" |
204 | | - }, |
205 | | - prod: { |
206 | | - client_id: "", |
207 | | - client_secret: "", |
208 | | - project_key: "", |
209 | | - oauth_host: "auth.sphere.io", |
210 | | - api_host: "api.sphere.io" |
211 | | - } |
212 | | -} |
213 | | -``` |
214 | | - |
215 | | -## Releasing |
216 | | -Releasing a new version is completely automated using the Grunt task `grunt release`. |
217 | | - |
218 | | -```javascript |
219 | | -grunt release // patch release |
220 | | -grunt release:minor // minor release |
221 | | -grunt release:major // major release |
222 | | -``` |
223 | | - |
224 | | -## Styleguide |
225 | | -We <3 CoffeeScript! So please have a look at this referenced [coffeescript styleguide](https://github.com/polarmobile/coffeescript-style-guide) when doing changes to the code. |
226 | | - |
227 | | -## License |
228 | | -Copyright (c) 2013 Nicola Molinari |
229 | | -Licensed under the MIT license. |
| 3 | +This repo has been integrated into `sphere-node-sdk`, please use related [npm package](https://www.npmjs.org/package/sphere-node-sdk) as well. |
0 commit comments