# apimstacker-client

> Client driver of Stacker APIM instance

Latest version **1.0.0** (published 2017-06-30) · SEE LICENSE IN LICENSE.txt license · 0 weekly downloads

## Install

```sh
npm install apimstacker-client
pnpm add apimstacker-client
yarn add apimstacker-client
bun add apimstacker-client
```

Provides the command `apimstack`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2017-06-30 |
| First published | 2017-06-30 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.txt |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | IBM API Connect |
| Maintainers | kraman |

## Links

- npm: https://www.npmjs.com/package/apimstacker-client
- Repository: https://github.ibm.com/apimesh/apimstacker-client
- npm.io page: https://npm.io/package/apimstacker-client

## Dependencies (2)

- [url](https://npm.io/package/url.md) ^0.11.0
- [request](https://npm.io/package/request.md) ^2.72.0

## Recent versions

- 1.0.0 (latest) — 2017-06-30

## README

# apimstacker-client

Client API and CLI to access APIM instance of Stacker service

## About Stacker

Stacker is a simple, trust-based resource sharing broker service.  APIM Stacker is an instance of
Stacker that manages a pool of APIM server stacks.

`apimstacker-client` is a Nodejs client driver for APIM instance of Stacker service.  Clients can use the CLI to acquire/release an apim stack manually or use API for programmatic access.


## CLI: `apimstack acquire <jobId>`

jobId {String} -- Any string can be used.  naming convention: use 'test-*' for short unit test jobs, or use your email address.

## CLI: `apimstack release <jobId>`

jobId {String} -- jobId used in the acquire command.

## CLI: `apimstack list`

shows the current state of the APIMStacker service.


## API: acquireApimStack

`acquireApimStack` is the only API currently supported.  Design goal of Stacker is to add minimum
functionality and let the users cooperate.  For example, multiple users can acquire the same
APIM server using the same jobId to share it.  Even after it's released, the Stacker does not
prevent the releaser from access to the released APIM server.  When it's
acquired by other user, multiple parties will share the resource.

- `jobId` a string to uniquely identify client
- `callback` {Function} called with the acquired `server` url.  If the stacker pool is full,
  it will be delayed indefinitely until an APIM server url is released or expired.
      - `server` {String} APIM server url, e.g., 'sjsldev679.dev.ciondemand.com'
      - `releaseApimStack` {Function} the user must call this function to release it to the pool.


## Example

```javascript
var JOB_ID = 'test-apis-' + (process.env.TRAVIS_JOB_ID ||
  require('os').hostname() + '-' + Date.now());

require('apimstacker-client').acquireApimStack(JOB_ID,
  function(server, releaseApimStack) {
  // server {String} url of the acquired APIM server, e.g., 'sjsldev789.dev.ciondemand.com'
  // releaseApimStack {Function} 

  // begin: example code to access the acquired APIM server
  process.env.APIM_MANAGEMENT = server;

  ...

  //end: example code to access the acquired APIM server

  delete process.env.APIM_MANAGEMENT;
  releaseApimStack();
  });
```
![apimstacker_diagram](./assets/images/20160710APIMStacker.png)

## APIMStacker REST API

Ask your Stacker administrator and get the REST endpoint, e.g., apimstacker.stage1.myblumix.net.

### Url
Shows the APIMStacker REST API help.
```
http://apimstacker.stage1.mybluemix.net/
```
### Response
```txt
____ APIM Stacker ____
-- show apim stack status:
https://apimstacker.stage1.mybluemix.net/dump-pool
-- acquire stack url:
https://apimstacker.stage1.mybluemix.net/acquire-stack/:jobid
-- release stack url:
https://apimstacker.stage1.mybluemix.net/release-stack/:jobid
```

### Url
Shows the current status of the APIMStacker pool.
```
https://apimstacker.stage1.mybluemix.net/dump-pool
```
### Response
```javascript
{
"version":"1.0.0",
"description":"APIM Stacker",
"servers":{
  "sjsldev679.dev.ciondemand.com":{"id":"","acquiredAt":0,"reachable":true,"checkedAt":0},
  "sjsldev967.dev.ciondemand.com":{"id":"","acquiredAt":0,"reachable":true,"checkedAt":0},
  "sjsldev803.dev.ciondemand.com":{"id":"","acquiredAt":0,"reachable":true,"checkedAt":0},
  "sjsldev769.dev.ciondemand.com":{"id":"","acquiredAt":0,"reachable":true,"checkedAt":0},
  "sjsldev911.dev.ciondemand.com":{"id":"","acquiredAt":0,"reachable":true,"checkedAt":0}
  },
"queue":[]
}
```

### Url
Acquires an APIM server.  The jobId can be any string that uniquely identifies the client as the acquirer.  The acquired APIM server url will be released when it expires.  To extend, simply call acquire-stack with the same jobId.

Unit test jobs expire much sooner (like 10 min. vs. 3 hrs) than other jobs.  If the jobId starts with 'test-', it's deemed as a test job.

```
https://apimstacker.stage1.mybluemix.net/acquire-stack/tseto@us.ibm.com
```
### Response
```
{"jobId":"tseto@us.ibm.com","server":"sjsldev789.dev.ciondemand.com"}
```

### Url
Releases the acquired APIM server.  The jobId is the string used when the server was acquired.   The acquired APIM server url will be automatically released to the pool when it expires.  Your Stacker service administrator sets the grace period, for example, three hours. 

```
https://apimstacker.stage1.mybluemix.net/release-stack/tseto@us.ibm.com
```
### Response
```
{"jobId":"tseto@us.ibm.com","server":""}
```

---
_Source: https://npm.io/package/apimstacker-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._