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

## Get Licenses - 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 Mend. | 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"
                }
            ]
        }
    ]
}
```

## Get Licenses - 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 Mend. | 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"
                }
            ]
        }
    ]
}
```

## Get Licenses - 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 Mend. | 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.

## Get Licenses Histogram - 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 Mend. | 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
    }
}
```

## Get Licenses Histogram - 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 Mend. | 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
    }
}
```

## Get Licenses Histogram - 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 Mend. | 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.

## Get Licenses Text Zip File - 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 Mend. | 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


## Get Licenses Text Zip File - 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 Mend. | 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.

## Get Copyrights Text File - 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 Mend. | string | Yes |
| **showCopyrightExtraDetails** | If you manually change copyright for a given library, when the flag is set to `true`, it will return the name of the user who modified the copyright assignment, as shown in the Mend Application. | string | Yes, only in API v1.4 |


#### Request Example


```
{
	"requestType" : "getCopyrightsTextFile",
     "userKey": "user_key", 
	"productToken" : "product_token",
	"showCopyrightExtraDetails": "true"
}
```

#### Response Format

The response will have the following headers:

* Content-Type = text/plain
* Content-Disposition: attachment; filename=product_name-copyrights.zip


## Get Copyrights Text File - 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 Mend. | string | Yes |
| **showCopyrightExtraDetails** | If you manually change copyright for a given library, when the flag is set to `true`, it will return the name of the user who modified the copyright assignment, as shown in the Mend Application. | string | Yes, only in API v1.4 |


#### Request Example


```
{
    "requestType" : "getProjectCopyrightsTextFile",
     "userKey": "user_key",
    "projectToken" : "project_token",
    "showCopyrightExtraDetails": "true"
}
```

#### 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 Mend. | 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 Mend. | 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": "text of the notice", 
  "reference": "additional library reference information"
}
```

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.

## Get Library Locations - 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 Mend. | 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"
			}
		]
	}
]
```

## Get Library Locations - 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 Mend. | 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"
			}
		]
	}
]
```

# Get Source Library Info

This API enables users to retrieve a source library from the [Mend.io](http://Mend.io) index.
Use-case: You can use this API to establish the *keyUuid* of the desired source library for re-mapping source files using the *changeOriginLibrary* API call.

#### QUERY PARAMETERS

| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | API request type that changes the origin 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 Mend. | string | Yes |
| **owner** | The owner of the source library. | string | Yes |
| **name** | The name of the source library. | string | Yes |
| **version** | The version of the source library. | string | Yes |
| **host** | The platform hosting the source library (e.g., “github”). | string | Yes |
| **downloadLink** | The link to download the source library | string | No |


#### Request Example


```
{
    "requestType" : "getSourceLibraryInfo",
    "orgToken" : "<yourOrgToken>",
    "userKey": "<yourUserKey>",
    "owner":"apache",
    "name":"xerces-c",
    "version":"v2.7.0",
    "host":"github",
    "downloadLink": "https://github.com/apache/xerces-c/zipball/v1.0.0"
}
```

#### Response Example


```
{
    "keyUuid": "key_Uuid",
    "libraryName": "xerces-c-v1.0.0",
    "url": "https://github.com/apache/xerces-c.git"
}
```

# Change Origin Library

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

**NOTE:** By default, the `changeOriginLibrary` API runs synchronously. However, this API can also be generated asynchronously to prevent timeouts in large organizations with many projects.

#### QUERY PARAMETERS

| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | API request type that changes the origin 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 Mend. | string | Yes |
| **runAsync** | “true” or “false” depending on whether or not you want to run the API request asynchronously. | boolean | No |
| **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",
    "runAsync": "true",
    "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"
}
```