blackduck-api
Version:
Bluck Duck API for Node
276 lines (215 loc) • 10.2 kB
Markdown
# bluckduck-api.js
Black Duck API for Node
## Introduction
### Using this package
```javascript
$ mkdir test && cd test
$ npm init
$ vim package.json
Add: "type":"module"
$ npm install -s blackduck-api
$ cat > test.js
import { BlackDuckAPI, BlackDuckReports } from 'blackduck-api';
const bd = new BlackDuckAPI('http://blackduck.company.com/api', 'your_api_token');
bd.getBearer().then((bearer) => {
console.log(bearer);
});
CTRL+D
$ node test.js -- or --
$ node --experimental-modules test.js -- if you skipped the type:module step --
```
### What is supported?
- [x] List users, roles, projects, versions, components, bomcomponents and custom fields
- [x] Create/delete of a project, version and component
- [X] Simple reports for users, roles, projects, versions, components and bomcomponents
## Porcelain API
### Introduction
This table is an overview on supported functionality:
BlackDuck Type | Available Functions | Reports |
-------------- | ------------------------------------------------------------------------|--------------------------------------------|
user | users_object = listUsers(query, filter) | usersReport(users_object) |
role | roles_object = listRoles(query, filter) | rolesReport(roles_object) |
project | result = createProject(name) | |
project | result = deleteProject(name) | |
project | projects_object = listProjects(query, filter) | projectsReport(projects_object) |
version | result = createVersion(project_object, name) | |
version | result = deleteVersion(project_object, name) | |
version | versions_object = listVersions(project_object, query, filter) | versionsReport(versions_object) |
component | components_object = listComponents(version_object, query, filter) | componentssReport(components_object) |
bom | bomcomponents_object = listBomComponents(version_object, query, filter) | bomComponentssReport(bomcomponents_object) |
customfield | fileds_object = getCustomFields(project_object, query, filter) | |
### Authenticate to Black Duck Server
Create a authentication token in the Black Duck server.
> getBearer()
Example:
```javascript
import { BlackDuckAPI } from 'blackduck-api';
const bd = new BlackDuckAPI("http://blackduck.company.com/api", "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef==");
bd.getBearer().then((bearer) => {
log('Authenticated: ');
});
```
### General
All APIs returns:
* [[obj1}, ..., {objn}]] - query matched one or more objects
* [] - query matched nothing
* null - the request was rejected
To get detailed debug messages set the following environment varianle:
> $ export DEBUG=index.js
### Quering Projects
List projects
> getProjects(filter)
Filter:
* empty filter: list all
* available filters: name,projectTier,projectOwner
Example:
```javascript
...
bd.getBearer().then((bearer) => {
bd.getProjects('').then((projects) => {
console.log(projects);
});
});
```
### Quering versions
List versions
> getVersions(project_object, filter))
Filter:
* empty filter: list all
* available filters: versionName,nickname,phase
Example:
```javascript
bd.getProjects('name:someproject').then((projects) => {
bd.getVersions(projects[0], '').then((versions) => {
console.log(versions);
});
});
});
```
### Quering components
List components
> getComponents(version_object, filter))
Filter:
* empty filter: list all
* available filters: componentName,versionName
Example:
```javascript
bd.getProjects('name:someproject').then((projects) => {
bd.getVersions(projects[0], 'versioName:someversion').then((versions) => {
bd.getComponents(versions[0], '').then((components) => {
console.log(compoenents)
});
});
});
```
### Quering bill-of-materia
List BOM components
> getBomComponents(version_object, filter))
Filter:
* empty - no filter, list all
* componentName:component - search for a specific component
Example:
```javascript
bd.getProjects('name:someproject').then((projects) => {
bd.getVersions(projects[0], 'versioName:someversion').then((versions) => {
bd.getBomComponents(versions[0], '').then((components) => {
console.log(compoenents)
});
});
});
```
### Quering Users
List users
> getUsers(filter)
Filter:
* empty - no filter, list all
Example:
```
...javascript
bd.getBearer().then((bearer) => {
bd.getUsers('').then((users) => {
console.log(users);
});
});
```
### Quering Roles
List roles
> getRoles(filter)
Filter:
* empty - no filter, list all
Example:
```javascript
...
bd.getBearer().then((bearer) => {
bd.getRoles('').then((roles) => {
console.log(roles);
});
});
```
### Report Helpers
Some simpler reports are available to get started.
Example:
```javascript
import { BlackDuckAPI, BlackDuckReports } from 'blackduck-api.js';
const bd = new BlackDuckAPI(.., ...);
bd.getBearer().then((bearer) => {
bd.getProjects('').then((projects) => {
BlackDuckReports.projectReports(projects);
});
});
```
Print projects:
> BlackDuckReports.projectsReports(projects);
```
===================================================================================================
| total:1 | NAME | DATE | USER |
|---------------------------------------------------------------------------------------------------|
| project | project1 | 2020-06-25T14:58:26.967Z | user10 |
| project | project2 | 2020-06-25T14:58:26.967Z | user10 |
| project | project3 | 2020-06-25T14:58:26.967Z | user11 |
===================================================================================================
```
Print versions:
> BlackDuckReports.versionsReports(versions);
```
============================================================================================
| total:1 | NAME | DATE | USER | PHASE |
|--------------------------------------------------------------------------------------------|
| version | default | 2020-06-25T14:58:26.969Z | user10 | DEVELOPMENT |
| version | android | 2020-06-25T14:58:26.969Z | user10 | DEVELOPMENT |
| version | windows | 2020-06-25T14:58:26.969Z | user11 | DEVELOPMENT |
| version | default | 2020-06-25T14:58:26.969Z | user12 | DEVELOPMENT |
============================================================================================
```
Print components:
> BlackDuckReports.componentsReports(components);
Print bill-of-materias:
> BlackDuckReports.componentsBomReports(bomcomponents);
Print users:
> BlackDuckReports.usersReports(users);
```
===========================================================================================================================
| total:9 | NAME | FIRSTNAME | LASTNAME | EMAIL |
|---------------------------------------------------------------------------------------------------------------------------|
| users | user10 | Peter | Karlsson | peter.karlsson@gmail.com |
| users | user11 | Sten | Nilsson | sten.nilsson@gmail.com |
| users | user12 | Helge | Pettersson | helge.pettersson@gmail.com |
| users | user13 | Alexandra | Svensson | alexandra.svensson@gmail.com |
===========================================================================================================================
```
Print roles:
> BlackDuckReports.rolesBomReports(roles);
```
=====================================================================================================================
| total:8 | NAME | DESCRIPTION |
|---------------------------------------------------------------------------------------------------------------------|
| roles | Component Manager | This role can create, update and delete custom components. |
| roles | Global Code Scanner | This user can run code scans and map them to any project. |
| roles | Global Project Vi... | This role has read only access to all projects. |
| roles | License Manager | Ability to create/modify/delete licenses. |
| roles | Policy Manager | Ability to create/modify/delete policies. |
| roles | Project Creator | This role can create projects/versions and edit their settings. |
| roles | Super User | This role has access to all user and project data. This person can create/mod... |
| roles | System Administrator | This role will have access to system settings like the registration key, jobs... |
=====================================================================================================================
```