1 | # Portals [![Build Status](https://travis-ci.org/HelpfulHuman/Portals.svg?branch=master)](https://travis-ci.org/HelpfulHuman/Portals)
|
2 |
|
3 | Portals is a library for making XHR/AJAX requests with some syntactic sugar.
|
4 |
|
5 | The goals of this project are as follows:
|
6 |
|
7 | * Highly extensible
|
8 | * Shared options between requests
|
9 | * Supports promises (and uses ES6 promises when available)
|
10 | * Smallest file size possible (under 4kb minified desired)
|
11 | * As few dependencies as possible
|
12 |
|
13 | ## Getting Started
|
14 |
|
15 | ### Install via NPM
|
16 |
|
17 | ```
|
18 | npm install --save portals
|
19 | ```
|
20 |
|
21 | And make sure to `require` it:
|
22 |
|
23 | ```javascript
|
24 | var portals = require('portals')
|
25 | ```
|
26 |
|
27 | ### Install via Bower
|
28 |
|
29 | ```
|
30 | bower install --save portals
|
31 | ```
|
32 |
|
33 | ## Create an Instance
|
34 |
|
35 | Once installed, just instantiate an instance of the `Portal` constructor.
|
36 |
|
37 | ```javascript
|
38 | var http = new portals.Portal()
|
39 | ```
|
40 |
|
41 | ## Sending Requests
|
42 |
|
43 | Sending requests isn't all that different from other libraries of this nature. Simply supply a request object with url and method, along with any other request details you may need like a headers object, request body, etc...
|
44 |
|
45 | The `send()` method, and the helper methods, will return a standard promise with `then()` for successful (200 status code) responses and `catch()` for errors.
|
46 |
|
47 | ```javascript
|
48 | http.send({
|
49 | method: 'GET',
|
50 | url: '/some-endpoint',
|
51 | headers: {
|
52 | 'Accept': 'application/json'
|
53 | }
|
54 | })
|
55 | .then(function (res) {
|
56 | // do something with response
|
57 | })
|
58 | ```
|
59 |
|
60 | ### Helpers
|
61 |
|
62 | Portals offers the typical helper methods for making method specific calls like `GET`, `POST`, `PUT` and `DELETE`. These are basic shorthands and more advanced queries will want to make use of `send()`.
|
63 |
|
64 | ```javascript
|
65 | // GET
|
66 | http.get('/posts')
|
67 |
|
68 | // POST
|
69 | http.post('/posts', { id: 1, name: 'example' })
|
70 |
|
71 | // PUT
|
72 | http.put('/posts/1', { name: 'changed example' })
|
73 |
|
74 | // DELETE
|
75 | http.del('/posts/1')
|
76 | ```
|
77 |
|
78 | ## Interceptors
|
79 |
|
80 | Portals is made extensible via "interceptors". These are simply functions that have the capability to modify request and response data. Portals ships with a few standard interceptors that you can optionally use by calling the method `useDefaultInterceptors()`.
|
81 |
|
82 | ```javascript
|
83 | http.useDefaultInterceptors()
|
84 | ```
|
85 |
|
86 | If you want to cherry pick from the default interceptors, you can find them on the `interceptors` property and add them with the methods below.
|
87 |
|
88 | ```javascript
|
89 | var http = new portals.Portal()
|
90 | var encodeJsonRequestInterceptor = portals.interceptors.encodeJsonRequest
|
91 |
|
92 | http.onRequest(encodeJsonRequestInterceptor)
|
93 | ```
|
94 |
|
95 | ### Adding Interceptors
|
96 |
|
97 | You can add your own interceptors using either the `onRequest()` or the `onResponse()` methods.
|
98 |
|
99 | The `onRequest()` method adds a function that will be run when a request is about to go. It receives the `options` object for the request which contains information like method, url, headers, etc... Interceptors must return an object with strings for `method` and `url`.
|
100 |
|
101 | ```javascript
|
102 | var http = new portals.Portal()
|
103 |
|
104 | http.onRequest(function (config) {
|
105 | console.log('logging: ', config.url)
|
106 |
|
107 | return config
|
108 | })
|
109 |
|
110 | http.get('/my-endpoint')
|
111 | // will print "logging: /my-endpoint"
|
112 | ```
|
113 |
|
114 | The response interceptor is almost identical to the request interceptor, accept instead of an `options` object it receives and returns the `response` object for the completed request.
|
115 |
|
116 | ```javascript
|
117 | var http = new portals.Portal()
|
118 |
|
119 | http.onResponse(function (res) {
|
120 | res.body = 'intercepted!!!'
|
121 |
|
122 | return res
|
123 | })
|
124 |
|
125 | http.get('/my-endpoint')
|
126 | // response body will be "intercepted!!!"
|
127 | ```
|
128 |
|
129 | ## Features
|
130 |
|
131 | All features are just interceptors that come with the library. These are available on the `interceptors` property and are automatically added when `useDefaultInterceptors()` is called.
|
132 |
|
133 | ### Globals
|
134 |
|
135 | Often times you may need to set a global value, like a set of headers or default hostname for your request URLs. This is where using globals and the `mergeGlobalsRequest` interceptor comes in handy.
|
136 |
|
137 | ```javascript
|
138 | http.globals.hostname = 'http://some-api.com'
|
139 | http.globals.headers.Accept = 'application/yml'
|
140 |
|
141 | http.get('/my-endpoint')
|
142 | // will call "http://some-api.com/my-endpoint"
|
143 | ```
|
144 |
|
145 | ##### Standalone Usage
|
146 |
|
147 | ```javascript
|
148 | http.onRequest( portals.interceptors.mergeGlobalsRequest )
|
149 | ```
|
150 |
|
151 | ### Concatenate Hostname and Url
|
152 |
|
153 | Concatenates the `hostname` and `url` for the request if "http" is not present in the URL.
|
154 |
|
155 | ##### Standalone Usage
|
156 |
|
157 | ```javascript
|
158 | http.onRequest( portals.interceptors.buildUrlRequest )
|
159 | ```
|
160 |
|
161 | ### [PLANNED] URL Parameter Customization
|
162 |
|
163 | _Note: This interceptor has yet to be built._
|
164 |
|
165 | Allow tokens to be added to the url string and have those tokens replaced with matching key values from a "params" object.
|
166 |
|
167 | **Example:**
|
168 |
|
169 | ```javascript
|
170 | http.send({
|
171 | method: 'GET',
|
172 | url: '/posts/:postId',
|
173 | params: {
|
174 | postId: 100
|
175 | }
|
176 | })
|
177 |
|
178 | // hits "/posts/100"
|
179 | ```
|
180 |
|
181 | ##### Standalone Usage
|
182 |
|
183 | ```javascript
|
184 | http.onRequest( portals.interceptors.parseUrlParamsRequest )
|
185 | ```
|
186 |
|
187 | ### [PLANNED] Query String Configuration
|
188 |
|
189 | _Note: This interceptor has yet to be built._
|
190 |
|
191 | Builds a query string out of a "query" object.
|
192 |
|
193 | **Example:**
|
194 |
|
195 | ```javascript
|
196 | http.send({
|
197 | method: 'GET',
|
198 | url: '/posts',
|
199 | query: {
|
200 | page: 20
|
201 | }
|
202 | })
|
203 |
|
204 | // hits "/posts?page=20"
|
205 | ```
|
206 |
|
207 | ##### Standalone Usage
|
208 |
|
209 | ```javascript
|
210 | http.onRequest( portals.interceptors.buildQueryRequest )
|
211 | ```
|
212 |
|
213 | ### Encode JSON Request Body
|
214 |
|
215 | Encodes a `data` or `body` object as JSON if the `Content-Type` header contains `"json"` and sets it as the request body.
|
216 |
|
217 | ##### Standalone Usage
|
218 |
|
219 | ```javascript
|
220 | http.onRequest( portals.interceptors.encodeJsonRequest )
|
221 | ```
|
222 |
|
223 | ### Parse JSON Response Body
|
224 |
|
225 | Parses the `body` of the response if the `Content-Type` header contains `"json"`.
|
226 |
|
227 | ##### Standalone Usage
|
228 |
|
229 | ```javascript
|
230 | http.onRequest( portals.interceptors.parseJsonResponse )
|
231 | ```
|