Request Module
📦 Installation
const { Request } = require('@janiscommerce/request');|
|
|---|
| If you are using v1.x see the migration guide |
🔨 Usage
Request example
Making a custom request.
⚠️ When the response status code is greater than or equal to 400 throws an error.
try {
const { statusCode, body } = await Request.get('https://reqres.in/api/users');
console.log(`Status code: ${statusCode}`); // Status code: 200
console.log(body); // { message: 'OK' }
} catch(error){
console.log(error)
/*
{
name: 'RequestError'
message: 'Request failed: internal error',
code: 1
}
*/
}RequestSafe example
Making a custom safe request
⚠️ If you want to handle the error safely. NOT THROW
const { RequestSafe } = require('@janiscommerce/request');
const { statusCode, body } = await RequestSafe.get('https://reqres.in/api/users');
console.log(`Status code: ${statusCode}`); // Status code: 500
console.log(body); // { message: 'internal error' }
⚙️ Classes
- Request
-
Simple static class to make external request using http and http node core packages
- RequestSafe
-
Extend from Request. Its use is the same but not throw an error when the response status code is greater than or equal to 400
📄 Structures
-
PathTemplate :
string -
A string path. Supports templating in "{variable}" format. IE: "/api/users/{userId}/contacts"
-
CallOptions :
object -
RequestOptions :
object -
RequestResponse :
object
Request
Simple static class to make external request using http and http node core packages
Kind: global class
- Request
Request.lastRequest
To get the last request http method, endpoint, headers and body
Kind: static property of Request
Request.lastResponse
To get the last response status code, headers and body
Kind: static property of Request
Request.get(endpoint, [options]) ⇒ Promise.<RequestResponse>
To make a GET request
Kind: static method of Request
| Param | Type | Default |
|---|---|---|
| endpoint | string |
|
| [options] | RequestOptions |
{} |
Request.post(endpoint, body, [options]) ⇒ Promise.<RequestResponse>
To make a POST request
Kind: static method of Request
| Param | Type | Default |
|---|---|---|
| endpoint | string |
|
| body | any |
|
| [options] | RequestOptions |
{} |
Request.put(endpoint, body, [options]) ⇒ Promise.<RequestResponse>
To make a PUT request
Kind: static method of Request
| Param | Type | Default |
|---|---|---|
| endpoint | string |
|
| body | any |
|
| [options] | RequestOptions |
{} |
Request.patch(endpoint, body, [options]) ⇒ Promise.<RequestResponse>
To make a PATCH request
Kind: static method of Request
| Param | Type | Default |
|---|---|---|
| endpoint | string |
|
| body | any |
|
| [options] | RequestOptions |
{} |
Request.delete(endpoint, [options]) ⇒ Promise.<RequestResponse>
To make a DELETE request
Kind: static method of Request
| Param | Type | Default |
|---|---|---|
| endpoint | string |
|
| [options] | RequestOptions |
{} |
Request.call(options) ⇒ Promise.<RequestResponse>
PathTemplate : string
A string path. Supports templating in "{variable}" format. IE: "/api/users/{userId}/contacts"
CallOptions : object
Kind: global typedef Properties
| Name | Type | Description |
|---|---|---|
| headers | object |
Custom headers on request. Define as { [headerName]: headerValue } |
| pathParams | object |
Replace variables in path declared as "{variable}". Define structure as { [variableNameInPath]: valueForReplace } |
| queryParams | object |
Query parameters / filters on request. Define structure as { [queryVariableName]: value } |
| path | PathTemplate |
The request path |
| strictMode | boolean |
When this flag is set as true, the request response content-type should be application/json or error will thrown |
| endpoint | string |
The request endpoint. Protocol and path are optionals. When no protocol specified, http goes by default. Supports *PathTemplate |
| method | string |
The request method. 'GET' is set by default |
| body | any |
The request body (if request method accepts it). Can be a valid object, Array, string, or any serializable type. |
RequestOptions : object
Kind: global typedef Properties
| Name | Type | Description |
|---|---|---|
| headers | object |
Custom headers on request. Define as { [headerName]: headerValue } |
| pathParams | object |
Replace variables in path declared as "{variable}". Define structure as { [variableNameInPath]: valueForReplace } |
| queryParams | object |
Query parameters / filters on request. Define structure as { [queryVariableName]: value } |
| path | PathTemplate |
The request path |
| strictMode | boolean |
When this flag is set as true, the request response content-type should be application/json or error will thrown |
RequestResponse : object
Kind: global typedef Properties
| Name | Type | Description |
|---|---|---|
| complete | boolean |
Flag that represents that if operation was completed |
| aborted | boolean |
Flag that represents that if operation was aborted |
| httpVersion | string |
String with http protocol version of the response sent |
| rawHeaders | Array.<String> |
Request headers as array of srings |
| headers | object |
Response headers. Formatted as { [headerName]: headerValue } |
| statusCode | number |
Response status code |
| statusMessage | string |
Response status message |
| body | any |
Response body. Can be a valid object, Array, string, or any serializable type. |
| rawBody | Array |
Response body without serialization. |
| originRequest | CallOptions |
Used to make another request based on the origin request. Ie: For retry the same request |
🏃 Migration
Migration from v1.x to v2
Now Request, in addition to being required in another way, throws an error if the response status code if >= 400
If you want to keep the functionality of v1.x must require and change RequestSafe to your old Request as follows
// old way to require the package
const Request = require('@janiscommerce/request');
// new way
const { RequestSafe } = require('@janiscommerce/request');