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 |
---|---|---|---|
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
{ "requestType" : "getOrganizationLicenses", "userKey": "user_key", "orgToken" : "organization_api_key", "excludeProjectOccurrences" : true }
Response Example (JSON)
{ "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" }, ...........
Product
Get libraries and their licenses for a specific product.
QUERY PARAMETERS
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
{ "requestType" : "getProductLicenses", "userKey": "user_key", "productToken" : "product_token", "excludeProjectOccurrences" : false }
Response Example (JSON)
{ "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" } ] } ], ...........
Project
Get libraries and their licenses for a specific project.
QUERY PARAMETERS
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
{ "requestType" : "getProjectLicenses", "userKey": "user_key", "projectToken" : "project_token" }
Response Example (JSON)
"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" } } ]
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 |
---|---|---|---|
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
{ "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:
{ "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 } }
Product
Get a histogram of a product’s licenses and their number of occurrences.
QUERY PARAMETERS
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
{ "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:
{ "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 } }
Project
Get a histogram of a project’s licenses and their number of occurrences.
QUERY PARAMETERS
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
{ "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:
{ "licenseHistogram" : { "Apache 2.0" : 2, "BSD 3" : 2, "GPL 3.0" : 1, } }
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 |
---|---|---|---|
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
{ "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
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 |
---|---|---|---|
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
{ "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
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 |
---|---|---|---|
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
{ "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 |
---|---|---|---|
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
{ "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
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 |
---|---|---|---|
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
{ "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
Set Library Notices
This API request enables you to set a text value for a library’s notice.
QUERY PARAMETERS
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
{ "requestType": "setLibraryNotice", "orgToken" : "org_token", "userKey": "user_key", "libraryUUID": "library_UUID", "text": "Notices are fun!", "reference": "And references are too" }
Response Example
{ "message": "Successfully set notice" }
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 |
---|---|---|---|
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
{ "requestType" : "getProductLibraryLocations", "userKey": "user_key", "productToken" : "product_token" }
Response Example (JSON)
"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 |
---|---|---|---|
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
{ "requestType" : "getProjectLibraryLocations", "userKey": "user_key", "projectToken" : "project_token" }
Response Example (JSON)
"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" } ] } ]
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 |
---|---|---|---|
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
{ "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
{ "message": "Successfully changed origin library" }