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", }
Response Example (JSON)
{ "libraries": [ { "keyUuid": "56a58812-b304-44f7-a589-1911ee10757c", "keyId": 1, "filename": "commons-beanutils-1.8.0.jar", "type": "Java", "resolvedType": "Java", "description": "BeanUtils provides an easy-to-use but flexible wrapper around reflection and introspection.", "references": { "url": "http://commons.apache.org/beanutils/", "issueUrl": "http://issues.apache.org/jira/browse/BEANUTILS", "pomUrl": "https://repo.maven.apache.org/maven2/commons-beanutils/commons-beanutils/1.8.0/commons-beanutils-1.8.0.pom", "scmUrl": "http://svn.apache.org/viewvc/commons/proper/beanutils/trunk/" }, "directDependency": true, "projects": [ { "projectName": "Demo Data", "projectToken": "5715a92ea3d345d29512481363d8f9751b87c8fb50c44c46a44e81e90e7407e6" } ], "sha1": "0c651d5103c649c12b20d53731643e5fffceb536", "name": "Commons BeanUtils", "artifactId": "commons-beanutils", "version": "1.8.0", "groupId": "commons-beanutils", "licenses": [ { "name": "Apache 2.0", "spdxName": "Apache-2.0", "url": "http://www.opensource.org/licenses/Apache-2.0", "references": [ { "referenceType": "POM file", "reference": "https://repo.maven.apache.org/maven2/commons-beanutils/commons-beanutils/1.8.0/commons-beanutils-1.8.0.pom" } ] } ], "copyrightReferences": [ { "copyright": "Copyright 2000-2008 The Apache Software Foundation", "startYear": "2000", "endYear": "2008", "author": "The Apache Software Foundation", "textUrl": "/gri/app/reader/resource/content/asString/d549e4e9-ab82-4409-b19d-225c3e097be5" } ] } ] }
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 | Unique identifier of the product. | 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", }
Response Example (JSON)
{ "libraries": [ { "keyUuid": "56a58812-b304-44f7-a589-1911ee10757c", "keyId": 1, "filename": "commons-beanutils-1.8.0.jar", "type": "Java", "resolvedType": "Java", "description": "BeanUtils provides an easy-to-use but flexible wrapper around reflection and introspection.", "references": { "url": "http://commons.apache.org/beanutils/", "issueUrl": "http://issues.apache.org/jira/browse/BEANUTILS", "pomUrl": "https://repo.maven.apache.org/maven2/commons-beanutils/commons-beanutils/1.8.0/commons-beanutils-1.8.0.pom", "scmUrl": "http://svn.apache.org/viewvc/commons/proper/beanutils/trunk/" }, "directDependency": true, "projects": [ { "projectName": "Demo Data", "projectToken": "5715a92ea3d345d29512481363d8f9751b87c8fb50c44c46a44e81e90e7407e6" } ], "sha1": "0c651d5103c649c12b20d53731643e5fffceb536", "name": "Commons BeanUtils", "artifactId": "commons-beanutils", "version": "1.8.0", "groupId": "commons-beanutils", "licenses": [ { "name": "Apache 2.0", "spdxName": "Apache-2.0", "url": "http://www.opensource.org/licenses/Apache-2.0", "references": [ { "referenceType": "POM file", "reference": "https://repo.maven.apache.org/maven2/commons-beanutils/commons-beanutils/1.8.0/commons-beanutils-1.8.0.pom" } ] } ], "copyrightReferences": [ { "copyright": "Copyright 2000-2008 The Apache Software Foundation", "startYear": "2000", "endYear": "2008", "author": "The Apache Software Foundation", "textUrl": "/gri/app/reader/resource/content/asString/d549e4e9-ab82-4409-b19d-225c3e097be5" } ] } ] }
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 | 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" : "getProjectLicenses", "userKey": "user_key", "projectToken" : "project_token" }
Response Example (JSON)
{ "libraries": [ { "keyUuid": "991af093-4fae-4683-aef6-5f033df9b6d3", "keyId": 246, "filename": "xmlpull-1.1.3.1.jar", "type": "Java", "resolvedType": "Java", "references": { "url": "http://www.xmlpull.org", "issueUrl": "http://www.extreme.indiana.edu/bugzilla/buglist.cgi?product=XmlPull.org", "pomUrl": "https://repo.maven.apache.org/maven2/xmlpull/xmlpull/1.1.3.1/xmlpull-1.1.3.1.pom" }, "directDependency": false, "projects": [ { "projectName": "WST_464", "projectToken": "29a15e6d3d7744c09a3b9975e4bd6d702da71f13a0ab434aadd6a27f4db07849" } ], "sha1": "2b8e230d2ab644e4ecaa94db7cdedbc40c805dfa", "name": "XML Pull Parsing API", "artifactId": "xmlpull", "version": "1.1.3.1", "groupId": "xmlpull", "licenses": [ { "name": "Public Domain", "url": "http://creativecommons.org/licenses/publicdomain/", "references": [ { "referenceType": "POM file", "reference": "https://repo.maven.apache.org/maven2/xmlpull/xmlpull/1.1.3.1/xmlpull-1.1.3.1.pom" } ] } ], "copyrightReferences": [] } ] }
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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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" }