@molgenis/molgenis-api-client

molgenis-js-client

A javascript wrapper around the isomorphic-fetch API. Simplifies using REST api's by abstracting get, post, and delete and providing default options.

Installation

NPM

npm install @molgenis/molgenis-api-client --save

Yarn

yarn add @molgenis/molgenis-api-client

Usage

Import in your HTML

<script src="path/to/molgenis-api-client.js"></script>

<!-- Include a polyfill for ES6 Promises (optional) for IE11, UC Browser and Android browser support -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/core-js/2.4.1/core.js"></script>

Import as ES6 module

import api from '@molgenis/molgenis-api-client'

api.get(...)
api.post(...)
api.put(...)
api.delete_(...)
api.postFile(...)

CommonJS import

const api = require('@molgenis/molgenis-api-client/dist/molgenis-api-client.js')

api.get(...)
api.post(...)
api.put(...)
api.delete_(...)
api.postFile(...)

Examples

the molgenis-api-client supports three methods: get, post, and delete

GET examples

get('/api/v2/EntityType').then(response => {...}, error => {...}))
get('/api/v2/EntityType', { headers: { 'Content-type': 'text' } }).then(response => {...}, error => {...})

POST examples

const data = {
  'items': ['1', '2'],
  'id': 'example'
}

const options = {
  'body': JSON.stringify(data)
}

post('api/v2/PostData', options).then(response => {...}, error => {...})

const forceOptions = true
// options not merged with defaults
post('api/v2/PostData', options, forceOptions).then(response => {...}, error => {...}) 

PUT examples

const data = {
  items: ['1', '2'],
  status: 'SUCCESS'
}

const options = {
  body: JSON.stringify(data)
}

put('https://test.com/molgenis-test/put-something', options).then(response => {...}, error => {...})

DELETE examples

delete_('/api/v2/deleteById/1').then(response => {...}, error => {...})

POST_FILE examples

postFile('/plugin/one-click-importer/upload').then(response => {...}, error => {...})

Methods

Method	Description
api.get()	Performs a fetch with method 'GET'
api.post()	Performs a fetch with method 'POST'
api.put()	Performs a fetch with method 'PUT'
api.delete_()	Performs a fetch with method 'DELETE'
api.postFile()	Performs a fetch with method 'POST' and attached FormData() containing a 'file' parameter. Ignores other options

Options

The options object that can be supplied to different API methods can contain the following parameters.

Parameter	Description	Default value
method	GET, POST, PUT, DELETE, HEAD	Defaults to GET for get(), POST for post() and DELETE for delete() and PUT for put()
headers	associated Headers object	'headers': { 'Accept': 'application/json', 'Content-Type': 'application/json' }
referrer	referrer of the request	undefined
mode	cors, no-cors, same-origin	undefined
credentials	should cookies go with the request? omit, same-origin	same-origin
redirect	What to do on redirect. follow, error, manual	error
integrity	subresource integrity value	undefined
cache	cache mode default, reload, no-cache	undefined

ForceOptions

By default the passed options get merged with the default options. If you do not want to merge with the default options, but instead set all the options yourself, setting the forceOptions flag to true forces the passed options to be used as is.

forceOptions defaults to false

example:

 const forceOptions = true
 const options = { some: 'options'}
 post('api/v2/PostData', options, forceOptions)

Browser compatibility

IE11*	Edge	Chrome	Firefox	Safari	Opera	Android Browser*	UC Browser*
✅	✅	✅	✅	✅	✅	✅	✅

* ES6 Promise polyfill should be included, see this example.

Note that this library is used in bleeding edge front end development. We do not and will not provide support on IE8 or lower.

Contributing

This project uses Yarn for development, uses Mocha for testing and is compiled with Rollup

To get started: yarn install

To build: yarn build

To test: yarn test

To test with coverage: yarn test:cover

To get coverage: yarn coveralls

To lint: yarn lint

To debug: first add node-inspector: npm install -g node-inspector then run: yarn debug

Development

yarn dev to run dev server during development.

yarn test to run tests.

yarn build to create new production build.

How to commit

We use conventional commits to generate changelogs and release notes. Please check: https://www.conventionalcommits.org/

Example

git commit file.ext -m "fix(file.ext): fixes something"

How to publish

Each time a PR is merged a release will be done to NPM. The CHANGELOG.md and GitHub release will be ammended.

The version of the package is based upon convential commits. Check: http://commitizen.github.io/cz-cli/.

Changelog

Details changes for each release are documented in the CHANGELOG.md.

License

LGPL-3.0