@molgenis/molgenis-api-client

A javascript client for the molgenis api

Stats

StarsIssuesVersionUpdatedCreatedSize
@molgenis/molgenis-api-client
0213.1.49 months ago4 years agoMinified + gzip package size for @molgenis/molgenis-api-client in KB

Readme

codecov Commitizen friendly

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

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.