Licenses and Libraries API

Overview

This document showcases the API requests and responses for getting:

  • licenses at the organization, product, or project-level

  • licenses histogram (license name : occurrence) for a given organization, product or project

  • text of licenses terms and conditions contained in a single zip file

  • copyrights text file for a product or project

  • notices text file for a product

  • setting the text of a library’s notice

  • locations of libraries in a product or project

  • changing the library currently matched to source files

Get Licenses

This API request enables you to get all libraries and their licenses for a given organization, product or project.

Organization

Get libraries and their licenses for an organization.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns an organization’s licenses per library.

string

Yes

orgToken

API key which is a unique identifier of the organization. Used to identify the organization in plugins.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

excludeProjectOccurrences

“true” or “false” depending on whether or not you want to exclude project occurrences of the licenses.

boolean

No

Request Example

1 2 3 4 5 6 { "requestType" : "getOrganizationLicenses", "userKey": "user_key", "orgToken" : "organization_api_key", "excludeProjectOccurrences" : true }

Response Example (JSON)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 {     "libraries": [         {             "keyUuid": "e8a0f87f-e4e0-4d98-b582-9b45bba9f14e",             "keyId": 72104923,             "filename": "content-disposition-0.5.3.tgz",             "type": "javascript/Node.js",             "languages": "javascript/Node.js",             "description": "Create and parse Content-Disposition header",             "references": {                 "url": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.3.tgz",                 "homePage": "https://github.com/jshttp/content-disposition#readme",                 "genericPackageIndex": "https://www.npmjs.org/package/content-disposition"             },             "directDependency": false,             "projects": [],             "sha1": "e130caf7e7279087c5616c2007d0485698984fbd",             "name": "content-disposition",             "artifactId": "content-disposition-0.5.3.tgz",             "version": "0.5.3",             "groupId": "content-disposition",             "licenses": [                 {                     "name": "MIT",                     "spdxName": "MIT",                     "url": "http://www.opensource.org/licenses/MIT",                     "references": [                         {                             "referenceType": "NPM (details available in Node Package Manager)",                             "reference": "https://index.whitesourcesoftware.com/gri/app/reader/resource/content/asString/db68c4d9-eadd-4253-b225-414430934c92"                         },                         {                             "referenceType": "NPM (details available in Node Package Manager)",                             "reference": "https://index.whitesourcesoftware.com/gri/app/reader/resource/content/asString/68640e55-d246-495d-a376-9921d18084d7"                         },                         ...........

Back to top.

Product

Get libraries and their licenses for a specific product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a product's licenses per library.

string

Yes

productToken

API key which is a unique identifier of the product. Used to identify the product in plugins.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

excludeProjectOccurrences

“true” or “false” depending on whether or not you want to exclude project occurrences of the licenses.

boolean

No

Request Example

1 2 3 4 5 6 { "requestType" : "getProductLicenses", "userKey": "user_key", "productToken" : "product_token", "excludeProjectOccurrences" : false }

Response Example (JSON)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 {     "libraries": [         {             "keyUuid": "7adc8fca-33f8-4a37-b179-a1bfb3b26699",             "keyId": 542406,             "filename": "thor-0.19.1.gem",             "type": "Ruby",             "languages": "Ruby",             "description": "Thor is a toolkit for building powerful command-line interfaces.",             "references": {                 "url": "https://rubygems.org/gems/thor-0.19.1.gem",                 "homePage": "http://whatisthor.com/",                 "genericPackageIndex": "https://rubygems.org/gems/thor/versions/0.19.1"             },             "directDependency": false,             "projects": [                 {                     "projectName": "GH_cloudify-cli",                     "projectToken": "7d254ee8e3ba4f9b88bec55f8e95b07af98452e381d5478fa7b9a30ef47e71dd"                 }             ],             "sha1": "57d118b7ce6d51be06faab84c4ad5709977e098f",             "name": "thor",             "artifactId": "thor-0.19.1.gem",             "version": "0.19.1",             "groupId": "thor",             "licenses": [                 {                     "name": "MIT",                     "spdxName": "MIT",                     "url": "http://www.opensource.org/licenses/MIT",                     "references": [                         {                             "referenceType": "RubyGems (details available in Ruby community’s gem hosting service)",                             "reference": "https://index.whitesourcesoftware.com/gri/app/reader/resource/content/asString/8be8ce33-c57d-4ebc-ba7c-52be21c56c09"                         },                         {                             "referenceType": "RubyGems (details available in Ruby community’s gem hosting service)",                             "reference": "https://index.whitesourcesoftware.com/gri/app/reader/resource/content/asString/43734334-bd0b-49e8-9be9-446c15204ac1"                         }                     ]                 }             ],             ...........

Back to top.

Project

Get libraries and their licenses for a specific project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a project's licenses per library.

string

Yes

projectToken

API key which is a unique identifier of the project. Used to identify the project in plugins.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getProjectLicenses", "userKey": "user_key", "projectToken" : "project_token" }

Response Example (JSON)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 "libraries" : [ { "licenses" : [ "license_name_1", "license_name_2", "spdxName":"license_spdx_name" ], "copyrightReferences": [ { "copyright": "library_copyright_text", "startYear": "library_copyright_start_year" } ], "keyUuid": "library_key_uuid", "keyId": "library_key_id", "filename": "library_file_name", "name" : "libarary_name", "groupId" : "library_group_id", "artifactId" : "library_artifact_id", "version" : "library_version", "sha1" : "library_sha1", "languages": "library_language", "references" : {"url":"library_url", "downloadLink":"library_download_link" } } ]

Back to top.

Get Licenses Histogram

This API request enables you to get a licenses histogram for a given organization, product, or project.

Organization

Get a histogram of licenses and their number of occurrences for an organization.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a histogram of an organization’s licenses.

string

Yes

orgToken

API key which is a unique identifier of the organization. Used to identify the organization in plugins.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getOrganizationLicenseHistogram", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response Example (JSON)

The JSON response lists all the licenses and their number of occurrences in the specified organization. For example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 {     "licenseHistogram": {         "Unlicense": 4,         "GPL 3.0": 11,         "Apache 2.0": 331,         "Apache 1.1": 4,         "Mozilla 2.0": 1,         "Mozilla 1.1": 2,         "PIL Software License": 1,         "Suspected Proprietary": 1,         "GPL 2.0": 18,         "ICU License": 1,         "CC0": 4,         "BSD": 12,         "LGPL": 9,         "Academic 2.1": 1,         "Unspecified License": 19,         "CC BY 3.0": 1,         "ISC": 79,         "Common Public 1.0": 3,         "Oracle Binary (Java SE and JavaFX)": 1,         "Ruby": 5,         "Bouncy Castle License": 1,         "Eclipse 1.0": 31,         "Artistic 2.0": 2,         "CDDL 1.0": 4,         "CDDL 1.1": 27,         "Indiana University Extreme!": 3,         "Suspected Apache 2.0": 1,         "Unknown License": 26,         "Dom4j": 1,         "Custom": 1,         "Public Domain": 6,         "CDDL or GPLv2 with exceptions": 1,         "BSD 2": 22,         "BSD 3": 62,         "Python 2.0": 2,         "WTFPL": 2,         "LGPL 3.0": 4,         "LGPL 2.1": 55,         "MIT": 885,         "JTidy License": 1,         "Jacob": 1,         "GPL 2.0 Classpath": 18     } }

Back to top.

Product

Get a histogram of a product’s licenses and their number of occurrences.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a history of a product’s licenses.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getProductLicenseHistogram", "userKey": "user_key", "productToken" : "product_token" }

Response Example (JSON)

The JSON response lists all the licenses and their number of occurrences for the specified product. For example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 {     "licenseHistogram": {         "Artistic 2.0": 2,         "Apache 2.0": 43,         "Unknown License": 3,         "Mozilla 2.0": 1,         "GPL 2.0": 3,         "BSD 2": 2,         "BSD 3": 6,         "BSD": 2,         "ISC": 1,         "LGPL 3.0": 1,         "MIT": 45,         "Ruby": 5,         "Jacob": 1     } }

Back to top.

Project

Get a histogram of a project’s licenses and their number of occurrences.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a project’s licenses histogram.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getProjectLicenseHistogram", "userKey": "user_key", "projectToken" : "project_token" }

Response Example (JSON)

The JSON response lists the licenses and their number of occurrences for the specified project. For example:

1 2 3 4 5 6 7 { "licenseHistogram" : { "Apache 2.0" : 2, "BSD 3" : 2, "GPL 3.0" : 1, } }

Back to top.

Get Licenses Text Zip File

This API request enables you to get the text of licenses terms and conditions contained in a single zip file, for a product or project.

Product

Get a Licenses text zip file showing terms and conditions for a product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that gets a License text zip file for a product.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getLicensesTextZip", "userKey": "user_key", "productToken" : "product_token" }

Response Format

The response is a zip file, not a JSON formatted message. It will have the following headers:

  • Content-Type = application/zip

  • Content-Disposition: attachment; filename=product_name-licenses.zip

Back to top.

Project

This API request enables you to get a Licenses text zip file showing terms and conditions for a project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that gets a License text zip file for a project.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getProjectLicensesTextZip", "userKey": "user_key", "projectToken" : "project_token" }

Response Format

The response is a zip file, not a JSON formatted message. It will have the following headers:

  • Content-Type = application/zip

  • Content-Disposition: attachment; filename=project_name-licenses.zip

Back to top.

Get Copyrights Text File

This API request enables you to get a text file of all the Copyrights for a product or project.

Product

Get a text file of all the Copyrights for a product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that gets a Copyrights text file for a product.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getCopyrightsTextFile", "userKey": "user_key", "productToken" : "product_token" }

Response Format

The response will have the following headers:

  • Content-Type = text/plain

  • Content-Disposition: attachment; filename=product_name-copyrights.zip

Project

Get a text file of all the Copyrights for a project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that gets a Copyrights text file for a project.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getProjectCopyrightsTextFile", "userKey": "user_key", "projectToken" : "project_token" }

Response Format

The response will have the following headers:

  • Content-Type = text/plain

  • Content-Disposition: attachment; filename=project_name-copyrights.zip

Back to top.

Get Notices Text File

This API request enables you to get a text file of all the Notices for a product.

NOTE: This request is available ONLY for products.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that gets a Notices text file for a product.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getNoticesTextFile", "userKey": "user_key", "productToken" : "product_token" }

Response Format

The response will have the following headers:

  • Content-Type = text/plain

  • Content-Disposition: attachment; filename=product_name-notices.zip

Back to top.

Set Library Notices

This API request enables you to set a text value for a library’s notice.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that sets a library notice.

string

Yes

orgToken

API key which is a unique identifier of the organization. Used to identify the organization in plugins.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

libraryUUID

Unique ID of the library in which you want to set the notice.

string

Yes

text

Text of the library’s notice that you want to set.

string

Yes

reference

Optionally, add library reference information to the notice.

string

No

Request Example

1 2 3 4 5 6 7 8 { "requestType": "setLibraryNotice", "orgToken" : "org_token", "userKey": "user_key", "libraryUUID": "library_UUID", "text": "Notices are fun!", "reference": "And references are too" }

Response Example

1 2 3 { "message": "Successfully set notice" }

Back to top.

Get Library Locations

This API request enables you to get the path locations of all libraries in a product or project.

Product

Get the path locations of the libraries in a product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that gets the library locations for a product.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getProductLibraryLocations", "userKey": "user_key", "productToken" : "product_token" }

Response Example (JSON)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 "libraryLocations" : [ { "name" : "library_name", "keyId" : key_id, "keyUuid" : "key_uuid", "locations": [ { "path" : "library_location_1\library_name", "matchType": "SHA1" }, { "path": "library_location_2\\library_name", "matchType": "FILENAME" } ] } ]

Project

Get the path locations of the libraries in a project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that gets the library locations for a project.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

Request Example

1 2 3 4 5 { "requestType" : "getProjectLibraryLocations", "userKey": "user_key", "projectToken" : "project_token" }

Response Example (JSON)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 "libraryLocations" : [ { "name" : "library_name", "keyId" : key_id, "keyUuid" : "key_uuid", "locations": [ { "path" : "library_location_1\library_name", "dependencyFile" : "home/ubuntu/GiHubRepos/Samples123/pom.xml" "matchType": "SHA1" }, { "path": "library_location_2\\library_name", "dependencyFile" : "home/ubuntu/GiHubRepos/Samples234/pom.xml" "matchType": "FILENAME" } ] } ]

Back to top.

Change Original Library

This API request enables you to change the library that is currently matched to the source files in your organization’s inventory.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that changes the original library of your source files.

string

Yes

orgToken

API key which is a unique identifier of the organization. Used to identify the organization in plugins.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

targetKeyUuid

Unique ID of the library to which you want to change the source files.

string

Yes

sourceFiles

An array of the source files to be moved.

array

Yes

userComments

Optionally, add a comment to this action.

string

No

Request Example

1 2 3 4 5 6 7 8 { "requestType" : "changeOriginLibrary", "userKey": "userKey", "orgToken" : "orgToken", "targetKeyUuid": "key-uuid-of-the-source-library-to-change-files", "sourceFiles": ["sha1_1", "sha1_2"], "userComments": "user-comments" }

Response Example

1 2 3 { "message": "Successfully changed origin library" }

Back to top.