Skip to content

Commit 3584a76

Browse files
marcuspoehlsmarcuspoehls
committed
wip
1 parent a090f5a commit 3584a76

File tree

4 files changed

+483
-471
lines changed

4 files changed

+483
-471
lines changed

‎requests.md

Lines changed: 1 addition & 243 deletions
Original file line numberDiff line numberDiff line change
@@ -2,247 +2,5 @@
22

33

44
## Introduction
5-
Supercharge uses the [hapi web framework](https://hapijs.com) as the core for routing and request handling. Hapi comes with a solid HTTP core and the handy feature of decorating the request object. Decorations allow you to add your own properties or functions on the `request` object.
5+
Tba.
66

7-
Supercharge comes with dozens of request utilities provided by the [`hapi-request-utilities`](https://github.com/futurestudio/hapi-request-utilities) package. This package is available for everyone on GitHub and NPM. Feel free to install it in your app:
8-
9-
- [`hapi-request-utilities`](https://github.com/futurestudio/hapi-request-utilities)
10-
11-
Enjoy!
12-
13-
14-
## Request Method and Path
15-
You've access to an incoming HTTP `request` in all route handlers and request lifecycle methods, including request lifecycle extension points and pre-handlers. The following reviews the important parts of the `request` instance and how to retrieve specific data from it.
16-
17-
18-
#### Retrieve the Request Method
19-
The HTTP verb (method) of an incoming request is a property on the request instance:
20-
21-
```js
22-
const method = request.method
23-
```
24-
25-
26-
#### Retrieve the Request Path
27-
Use the `path` property to retrieve a request's path. For example, when requesting `https://superchargejs.com/docs/request`, the `path` returns `/docs/request`.
28-
29-
```js
30-
const path = request.path
31-
```
32-
33-
34-
## Retrieve Request Input
35-
Interacting with a request input allows you to access information like path and query parameters, payload, headers, cookies, authenticated credentials, and request or response types.
36-
37-
38-
#### Retrieve All Request Data
39-
Use the `all` method to retrieve an object of merged request properties from the request's `payload`, `path`, and `query` parameter data.
40-
41-
```js
42-
const all = request.all()
43-
// Example: { searchTerm: 'Super Charge', page: 3}
44-
```
45-
46-
When merging the input from all three inputs, query parameters prioritize over path parameters and path parameters prioritize over payload.
47-
48-
49-
#### Retrieve an Input Item
50-
Retrieve a single input item identified by `key`. The request input is the request payload, path and query parameters. Internally, this method fetches the `key` from [`request.all()`](/docs/{{version}}/requests#retrieve-all-request-data).
51-
52-
```js
53-
const username = request.input('username')
54-
```
55-
56-
You can also pass a default value as the second parameter:
57-
```js
58-
const username = request.input('username', 'default-value')
59-
```
60-
61-
62-
#### Retrive Multiple Input Items
63-
Retrieve an object containing only the selected `keys` from the request payload, path and query parameters.
64-
65-
```js
66-
const { username } = request.only('username')
67-
68-
// or an array
69-
const { email, password } = request.only(['email', 'password'])
70-
```
71-
72-
The inverse method to `request.only` is `request.except` returning an object containing all attributes from the request payload, path and query parameters **except** the given `keys`.
73-
74-
```js
75-
const withoutToken = request.except('token')
76-
// Example: { email: 'email@example.com', secret: 'psssst', password: 'super1' }
77-
78-
const withoutSecrets = request.except(['token', 'password', 'secret'])
79-
// Example: { email: 'email@example.com' }
80-
```
81-
82-
83-
#### Determine If an Input Is Present
84-
Use `.has(keys)` to determine whether the request includes an input `key` or a list of `keys`.
85-
86-
```js
87-
if (request.has('email')) {
88-
//
89-
}
90-
91-
// or check an array
92-
if (request.has(['username', 'email'])) {
93-
//
94-
}
95-
```
96-
97-
When checking an array of keys, the `has` method returns `true` if all of the keys are present.
98-
99-
100-
To ensure a given key is present on the request and includes a non-empty value, use the `filled` method:
101-
102-
```js
103-
if (request.filled('email')) {
104-
//
105-
}
106-
107-
// or check an array
108-
if (request.filled(['username', 'email'])) {
109-
//
110-
}
111-
```
112-
113-
You can check an array of keys and `filled` will return true if all of the keys have non-empty values.
114-
115-
116-
#### Determine If an Input Is Missing
117-
Use `.missing(keys)` to determine whether the request missing an input `key` or a list of `keys`.
118-
119-
```js
120-
if (request.missing('email')) {
121-
//
122-
}
123-
124-
// or check an array
125-
if (request.missing(['username', 'email'])) {
126-
//
127-
}
128-
```
129-
130-
131-
### Headers
132-
All request headers are stored in the `headers` property.
133-
134-
```js
135-
const headers = request.headers
136-
```
137-
138-
You can request a single header by name using the `header` method:
139-
140-
```js
141-
const accept = request.header('accept')
142-
// Example: accept = 'application/json'
143-
```
144-
145-
To determine whether a request header is present on the request, use the `hasHeader` method:
146-
147-
```js
148-
const hasAccept = request.hasHeader('accept')
149-
// false
150-
```
151-
152-
153-
154-
### Cookies
155-
A request's cookies are stored within a `state` property on the request instance:
156-
157-
```js
158-
const cookies = request.state
159-
```
160-
161-
For naming consistency and readability, you can also use the `cookies` method to retrieve all request cookies:
162-
163-
```js
164-
const cookies = request.cookies()
165-
// Example: { userId: 1, username: 'supercharge' }
166-
```
167-
168-
Retrieve a selected request cookie by name using the `cookie` method:
169-
170-
```js
171-
const userId = request.cookie('userId')
172-
// Example: userId = 1
173-
```
174-
175-
Determine whether a selected cookie is present on the request with the help of the `hasCookie` method:
176-
177-
```js
178-
const hasUserId = request.hasCookie('userId')
179-
```
180-
181-
182-
### Authenticated Credentials
183-
If your application supports a login and a user successfully authenticated against your application, you can retrieve the credentials of an authenticated via the `user` property:
184-
185-
```js
186-
const credentials = request.user
187-
// the same as request.auth.credentials
188-
// Example: { id: 1, username: 'marcus' }
189-
```
190-
191-
Remember that calling `request.user` before `onPostAuth` in the request lifecycle will result in an `undefined` value. Credentials are available as soon as the request is authenticated.
192-
193-
When authenticating users with the help of bearer tokens, you may retrieve an incoming bearer token from the `Authorization` request header using the `bearerToken` method. This method will strip the `Bearer ` prefix and only return the token value:
194-
195-
```js
196-
const token = request.bearerToken()
197-
// Example: token = eyJhbGciOiJIUzI…
198-
```
199-
200-
201-
### Request and Response Types
202-
Determine whether the request has a `content-type` header includes `/json` or `+json`:
203-
204-
```js
205-
const isJson = request.isJson()
206-
// false
207-
```
208-
209-
You may also check the incoming request for a specific response format. If you support HTML and JSON responses on individual routes, the `wantsJson` method is a helpful method. It indicates whether the response should be a JSON string. It checks the `accept` header to indicate JSON:
210-
211-
```js
212-
const wantsJson = request.wantsJson()
213-
// false
214-
```
215-
216-
Supercharge provides a companion method `wantsHtml` indicating whether the response should be HTML. It checks the `accept` header to indicate HTML:
217-
218-
```js
219-
const wantsHtml = request.wantsHtml()
220-
// true
221-
```
222-
223-
224-
## Retrieve Request URLs
225-
You can also retrieve the reuqest URL or parts of the request URL from the `request` object. The folllowing code snippets use a request against `https://sub.domain.com/path/second-path?query=string#hashtag` to illustrate the results.
226-
227-
Use the `.root()` method to retrieve the request’s root domain:
228-
229-
```js
230-
const root = request.root()
231-
// https://sub.domain.com
232-
```
233-
234-
You may retrieve the domain including path parameter using the `.uri()` method:
235-
236-
```js
237-
const root = request.uri()
238-
// https://sub.domain.com/path/second-path
239-
```
240-
241-
Please notice that `request.url` is a property of the hapi framework providing a WHATWG URL instance.
242-
243-
You can also retrieve the full request domain including all parameters using `.fullUri()` method. You may also use `.fullUrl()` which is an alias for `.fullUri()`.
244-
245-
```js
246-
const root = request.fullUri()
247-
// https://sub.domain.com/path/second-path?query=string#hashtag
248-
```

0 commit comments

Comments
 (0)