apifetch-json
v2.1.3
Published
ApiFetch is a fetch() wrapper that provides an easy to read API for reading and writing JSON objects over HTTP(S) and REST apis
Downloads
7
Maintainers
Readme
ApiFetch (apifetch-json)
ApiFetch is a fetch() wrapper that provides an easy to read API for reading and writing JSON objects over HTTP(S) and REST apis.
ApiFetch provides methods for the HTTP commands:
- get()
- post()
- put()
- patch() And a generic
- fetch()
Each method can have its return type set (in Typescript) which will be deserialized from the servers result:
let myModel = ApiFetch.get<MyModel>('https://.../');
You can pass an object in that will be seralized as the body of the request:
let animal = { name: 'frog', color: 'blue' };
let myModel = ApiFetch.post<MyModel>('https://.../', animal);
The API will be familiar for anyone who is has used fetch() before, but with a lot of the boiler plate removed.
Installation
ApiFetch is available as apifetch-json on npm.
Install with npm:
npm install apifetch-json
Or with yarn:
yarn add apifetch-json
Basic Usage
Import
import { ApiFetch } from 'apifetch-json';
Get
get() will fetch() the passed in URL with the HTTP GET method and return the deserilized json object from the result.
let api = new ApiFetch();
let myModel = api.get<MyModel>('https://.../');
Post
post() will fetch() the passed in URL with the HTTP POST method, passing a JSON serizlied version of the passed in body object as the requests body and return the deserilized json object from the result.
let animal = { name: 'frog', color: 'blue' };
let api = new ApiFetch();
let myModel = api.post<MyModel>('https://.../', animal);
Put
put() will fetch() the passed in URL with the HTTP PUT method, passing a JSON serizlied version of the passed in body object as the requests body and return the deserilized json object from the result.
let animal = { name: 'frog', color: 'blue' };
let api = new ApiFetch();
let myModel = api.put<MyModel>('https://.../', animal);
Patch
patch() will fetch() the passed in URL with the HTTP PATCH method, passing a JSON serizlied version of the passed in body object as the requests body and return the deserilized json object from the result.
let animal = { name: 'frog', color: 'blue' };
let api = new ApiFetch();
let myModel = api.patch<MyModel>('https://.../', animal);
Delete
delete() will fetch() the passed in URL with the HTTP DELETE method, passing a JSON serizlied version of the passed in body object as the requests body and return the deserilized json object from the result.
let animal = { name: 'frog', color: 'blue' };
let api = new ApiFetch();
let myModel = api.delete<MyModel>('https://.../', animal);
Fetch
fetch() gives you full access to pass your own parameters to fetch including setting up your own RequestInit for init, and will return the deserilized json object from the result.
let api = new ApiFetch();
let myModel = ApiFetch.fetch<MyModel>('https://.../', { method: 'POST', headers: {/*...*/}, body: '...'});
Authorization and Other Defaults
ApiFetch's constructor accepts an optional RequestInit that will be applied to all requests made by the class. This is very useful to use to default headers for authorization or other information that should be passed to each call.
Example for authorization:
let api = new ApiFetch({
headers: {
'Authorization': `Bearer ${userState.token}`
}
});
// Later in the code...
api.get('https://...'); // Will pass the previously configured Authorization header.
Caching
ApiFetch's constructor also accepts optional FetchCatch object that will can be used to store the results of cachable requests for the life of the ApiFetch object.
ApiFetch comes with MemoryFetchCache an implementation of FetchCache that stored cached values in memory.
let cache = new MemoryFetchCache();
let api = new ApiFetch(init, cache);
You can then specify which items should be cached and for how long when you make calls:
api.get('https://...', { expireAt: new Date('2020-01-01')}); // If we call the same URL again it will use the cached results until they expire.
It is often more expire cached responses when events happen (e.g. when you post changes to the server) rather than at a time, this can be acheived by passing an array of string event names to expireOnEvents:
api.get('https://...', { expireOnEvents: ['model-changed', 'game-over']}); // Will be cached until 'model-changed' or 'game-over' events are triggered.
You can raise an event using the raiseExpireEvents() method:
api.raiseExpireEvents('game-over', 'user-changed'); // Will remove all cached items that expire on either the event 'game-over' or 'user-changed'.
Custom Caches
While the MemoryFetchCache class is useful for basic caching, you sometimes want to provide your own cache object that provides your own storage or logic (e.g. using Redux for cached values or persisting values to localStorage).
To do this you can simply implement the FetchCache interface and pass your custom class as the FetchCache to the ApiFetch constructor:
class CustomFetchCache {
/**
* Read the entry for id from the cache, returning null if it is not found.
* @param id
*/
readFromCache(input: string, init: RequestInit): any {
// Custom code here.
}
/**
* Store data in the cache for id.
* @param id
* @param data
* @param options
*/
storeInCache(input: string, init: RequestInit, result: any, options: FetchCacheOptions): void {
// Custom code here.
}
/**
* Remove all entries from the cache that are listining to any of the provided events.
* @param events
*/
raiseExpireEvents(...events: Array<string>): void {
// Custom code here.
}
}
let cache = new CustomFetchCache();
let api = new ApiFetch(init, cache);
Javascript Usage
ApiFetch works just as well with Javascript as Typescript. All you need to do is remove the type information from the above examples.
Here are the basic usage examples in plain Javascript:
Import
import { ApiFetch } from 'apifetch-json';
Get
var api = new ApiFetch();
var myModel = api.get('https://.../');
Post
var animal = { name: 'frog', color: 'blue' };
var api = new ApiFetch();
var myModel = api.post('https://.../', animal);
Put
var animal = { name: 'frog', color: 'blue' };
var api = new ApiFetch();
var myModel = api.put('https://.../', animal);
Patch
var animal = { name: 'frog', color: 'blue' };
var api = new ApiFetch();
var myModel = api.patch('https://.../', animal);
Delete
var animal = { name: 'frog', color: 'blue' };
var api = new ApiFetch();
var myModel = api.delete('https://.../', animal);
Fetch
var api = new ApiFetch();
var myModel = ApiFetch.fetch<MyModel>('https://.../', { method: 'POST', headers: {/*...*/}, body: '...'});
Typescript
This project is written in typescript and comes with its own bindings.
License
Licensed under the MIT license.