Table of Contents

maxLevel	2

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

Code Block
{ "requestType" : "getOrganizationLicenses", "userKey": "user_key", "orgToken" : "organization_api_key", "excludeProjectOccurrences" : true }

Response Example (JSON)

Code Block

{
    "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
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

Code Block
{ "requestType" : "getProductLicenses", "userKey": "user_key", "productToken" : "product_token", "excludeProjectOccurrences" : false }

...

Code Block

{
    "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
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

Code Block
{ "requestType" : "getProjectLicenses", "userKey": "user_key", "projectToken" : "project_token" }

Response Example (JSON)

Code Block

"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
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

Code Block
{ "requestType" : "getOrganizationLicenseHistogram", "userKey": "user_key", "orgToken" : "organization_api_key" }

...

Code Block

{
    "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
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

Code Block
{ "requestType" : "getProductLicenseHistogram", "userKey": "user_key", "productToken" : "product_token" }

...

Code Block

{
    "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
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

Code Block
{ "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:

Code Block
{ "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
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

Code Block
{ "requestType" : "getLicensesTextZip", "userKey": "user_key", "productToken" : "product_token" }

...

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
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

Code Block
{ "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
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

Code Block
{ "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

Code Block
{ "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
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

Code Block
{ "requestType" : "getNoticesTextFile", "userKey": "user_key", "productToken" : "product_token" }

...

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
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

Code Block
{ "requestType": "setLibraryNotice", "orgToken" : "org_token", "userKey": "user_key", "libraryUUID": "library_UUID", "text": "Notices are fun!", "reference": "And references are too" }

...

Code Block
{ "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
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

Code Block
{ "requestType" : "getProductLibraryLocations", "userKey": "user_key", "productToken" : "product_token" }

...

Code Block

"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

Code Block
{ "requestType" : "getProjectLibraryLocations", "userKey": "user_key", "projectToken" : "project_token" }

...

Code Block

"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
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

Code Block

{
    "requestType" : "changeOriginLibrary",
    "userKey": "userKey",
    "orgToken" : "orgToken",
    "targetKeyUuid": "key-uuid-of-the-source-library-to-change-files",
    "sourceFiles": ["sha1_1", "sha1_2"],
    "userComments": "user-comments"
}

...

Code Block
{ "message": "Successfully changed origin library" }

Back to top.

Page Comparison

Versions Compared

Old Version 17

New Version 18

Key

Overview

Get Licenses

Organization

QUERY PARAMETERS

Request Example

Response Example (JSON)

Product

QUERY PARAMETERS

Request Example

Project

QUERY PARAMETERS

Request Example

Response Example (JSON)

Get Licenses Histogram

Organization

QUERY PARAMETERS

Request Example

Product

QUERY PARAMETERS

Request Example

Project

QUERY PARAMETERS

Request Example

Response Example (JSON)

Get Licenses Text Zip File

Product

QUERY PARAMETERS

Request Example

Project

QUERY PARAMETERS

Request Example

Response Format

Get Copyrights Text File

Product

QUERY PARAMETERS

Request Example

Response Format

Project

QUERY PARAMETERS

Request Example

Response Format

Get Notices Text File

QUERY PARAMETERS

Request Example

Set Library Notices

QUERY PARAMETERS

Request Example

Get Library Locations

Product

QUERY PARAMETERS

Request Example

Project

QUERY PARAMETERS

Request Example

Change Original Library

QUERY PARAMETERS

Request Example