A minimal wrapper around the fetch API using JS proxies that simplifies making HTTP requests for deno.
This module was extracted from
netzo/client-api
without oauth2
authorization, to make it more modular.
It exports 3 useful utility functions from
https://deno.land/x/unrested/mod.ts
:
createApi
: used to create an api client for the service you're using. AbaseUrl
parameter option is required.auth
: used to set authorization credentials of the api service you're using.paginate
: used for paginating between query results.
import { createApi } from "https://deno.land/x/[email protected]/mod.ts";
const api = await createApi({
baseURL: "https://jsonplaceholder.typicode.com",
});
// GET {baseURL}/users (types optional)
const users = await api.users.get<User[]>();
// PATCH {baseURL}/users/12 (types optional)
const user = await api.users[12].patch<User>({ name: "John" });
Call the appropriate method call to make a request:
.get()
.post()
.put()
.delete()
.patch()
For HTTP request methods supporting query parameters, add them to the method call.
// GET {baseURL}/users?search=john
const result = await api.users.get({ search: "john" });
::: tip URL encoding Query parameters are automatically URL encoded using
encodeURI
. You can pass the query parameters directly as an object. :::
To include dynamic API path segments, for example GET
request to /users/12
,
you have two options:
// GET {baseURL}/users/12 (chain syntax):
const user = await api.users(12).get<UserResult>();
// GET {baseURL}/users/12 (bracket syntax):
const user = await api.users[12].get<UserResult>();
For HTTP request methods supporting a payload, add it to the method call.
// POST request to {baseURL}/users
const result = await api.users.post({ name: "foo" });
You can add/overwrite client options on a method-level:
const result = await api.users.get({
headers: { "content-type": "application/json" },
onRequest: (request, options) => {
request.url = request.url.replace("/v1", "/v2");
},
onError: (request, options, error) => {
console.error(error);
},
});
The following table gives an overview of the currently supported auth types for the supported specs:
Auth Type | Support |
---|---|
No auth | ✅ |
Basic auth | ✅ |
Bearer token | ✅ |
API key | ✅ |
OAuth2 | ⌛ |
Requests will be sent without authorization by default. If your resource does not require any authorization details you may go ahead and start using your resource right away.
Basic auth schema is a simple authentication method built into the HTTP
protocol. The client must provide a user name and password when sending HTTP
requests. For this, the request contains a header field in the form of
Authorization: Basic <CREDENTIAL>
, where credential is the Base64 encoding of
username and password joined together by a single colon.
To use this auth type select HTTP
and basic
options, and fill-out the
following required fields:
username
password
Bearer auth (also referred to as token authentication) schema is a
simple HTTP authentication schema that uses security tokens (referred to as
bearer tokens). Bearer tokens are text strings that are included in the
request header in the form of Authorization: Bearer <TOKEN>
and act as access
keys.
To use this auth type select HTTP
and bearer
options, and fill-out the
following required fields:
token
API keys is a security schema that uses simple encrypted strings to identify an application or project that is calling the API. API keys include a key-value pair in the request headers or query parameters when sending requests to an API. After selecting this security schema from the dropdown field, you must provide the key-value pair before confirming to save your changes.
To use this auth type select API Key
, select how to send the API key
(header
, query
, or cookie
), and fill-out the following required fields:
name
value
::: warning Multiple API Keys Some APIs use security key pairs (API key and App ID) for authentication. For the time being we do not support multiple API Keys out of the box. :::
Hooks are async interceptors to hook into lifecycle events of the HTTP Request and Response. Hooks can be configured both for the base and for Requests. Base hooks run before the corresponding Request hook rather than overwriting them. This allows adding additional functionality at the Request level, while retaining base functionality common to all Requests.
There are four types of hooks:
onRequest
: runs before thefetch
request is dispatched. Allows modifyingrequest
andoptions
onRequestError
: runs if thefetch
request fails. Allows modifyingrequest
,options
anderror
onResponse
: runs after thefetch
response returns (afterresponse.body
is parsed and set toresponse._data
). Allows modifyingrequest
,options
andresponse
onResponseError
: runs if thefetch
response fails (whenresponse.ok
is not true). Allows modifyingrequest
,options
andresponse