FAIRsharing-API-Client

The JavaScript client for the FAIRsharing API. Works with node, webpack and native JS.

Usage

1 - Install

a - From npm (not available yet)

npm install fairsharing-api-client

b - From source:

git clone https://github.com/FAIRsharing/FAIRSharing-API-Client.git
cd FAIRSharing-API-Client/
npm install
npm pack

You can then add the path to the .tgz generated by npm pack to the package.json file of your application:

{
  "dependencies": {
    "fairsharing-api-client": "/path/to/fairsharing-api-client-0.0.1-alpha.0.tgz"
  }
}

c - From CDN

<script type="application/javascript" src="https://fairsharingapiclientcdn.netlify.app/fairsharing.min.js">
</script>
<script type="module">
    let client = fairsharingClient('https://api.fairsharing.org');
</script>

2- In node or compiling with webpack:

// import the client
const fairsharingClient = require("fairsharing-api-client")  
const server_url = "https://api.fairsharing.org"

// create the class by feeding it the URL of the API.
let client = fairsharingClient(server_url)

// Login with a promise
client.login("user", "password").then(async () => {
    // You can now execute all query asynchronously
    let types = await client.getTaxon(12);
    console.log(types)
    // Logout after you are done
    await client.logout();
}).catch((e)=> {
    console.log("ERROR:", e)
})

You can then transpile this code with webpack to make it available in the browser or execute it with node.

3 - In the browser:

<!-- Import the transpiled code -->
<script type="application/javascript" src="./node_modules/fairsharing-api-client/dist/fairsharing.min.js">
</script>
<!-- Alternatively, you can use it directly from the CDN 
<script type="application/javascript" src="https://fairsharingapiclientcdn.netlify.app/fairsharing.min.js">
</script>
-->


<!-- Now, client is a function available through window.client() -->
<script type="module">
    const server_url = 'https://api.fairsharing.org'
    let client = fairsharingClient(server_url)
    // When in the browser you can enable a cache that relies on the localStorage
    // The input is a timer in hours, default to 24 if none is given
    client.enableCache(1)

    client.login("user", "password").then(async () => {
        // First request hits the servers
        let types = await client.getTaxon(12);
        console.log(types)
        // Second request hits the cache
        types = await client.getTaxon(12);
        console.log(types)
        // Logout and clear the cache when you are done
        await client.logout();
        client.clearCache();
    }).catch((e)=> {
        console.log("ERROR:", e)
    })
</script>

4- Development:

Building:

If you modify the source code, you can rebuild the dist/ directory locally using:

npm run build

Alternatively, you can use the netlify continuous deployment pipeline rebuild it with a Pull Request.

Testing:

If you want to test the code using jest:

npm run test:unit

Documentation:

The online documentation is under continuous deployment and is hosted at netlify.
If you want to generate the documentation locally using jsdoc and tui-jsdoc-template:

npm run doc

To generate the documentation for the private methods (developers only) run:

npm run doc:private

The clientConfiguration file for the documentation in is /doc/doc.conf.js.