License Legal REST API - v2
The License Legal REST API was released in IQ Server release 113. This endpoint is only available with the Advanced Legal Pack. It allows you to:
License Legal Application Report Raw Data
This section of endpoints returns the raw JSON legal data for an application. Expert and explanation of data posted at the bottom of this page.
GET a License Legal Application Report Raw Data
The Application Report contains a list of all components within the application along with the license legal metadata. To get the latest License Legal Application Report, regardless of stage, you can issue a GET request to the following path
GET /api/v2/licenseLegalMetadata/application/{applicationPublicId}For example, to get the license legal application report for an application with id "MyApp" you could issue this request
curl -u admin:admin123 http://localhost:8070/api/v2/licenseLegalMetadata/application/MyApp
This cURL request will produce a JSON response of the following form
{
"components": [...],
"licenseLegalMetadata": [...]
}each component and license legal metadata element will be of the same form as shown in the example response for getting a License Legal Component Report.
GET a License Legal Application Report Raw Data By Stage
The Application Report contains a list of all components within the application along with the license legal metadata. To get the latest License Legal Application Report for a specific Stage you can issue a GET request to the following path
GET /api/v2/licenseLegalMetadata/application/{applicationPublicId}/stage/{stageId}For example, to get the license legal application report for an application with id "MyApp" at the "Release" stage you could issue this request
curl -u admin:admin123 http://localhost:8070/api/v2/licenseLegalMetadata/application/MyApp/stage/release
This cURL request will produce a JSON response of the following form
{
"components": [...],
"licenseLegalMetadata": [...]
}each component and license legal metadata element will be of the same form as shown in the example response for getting a License Legal Component Report.
Legal Attribution Report Templates
NEW IN RELEASE 126
The legal attribution HTML report can be generated from a template. The template allows the following fields to be configured:
- documentTitle: The title displayed at the top of the attribution report.
- header: Optional header which will be displayed at the top of the attribuiton report above the title.
- footer: Optional footer dislpayed at the bottom of the report.
- includeTableOfContents: if true a table of content containing links to component's and their licenses will be added to the report.
- includeStandardLicenseTexts: if true, the standard license text will be displayed for component's with no License files.
- includeAppendix: if true, the standard license text will be grouped together in the the report appendix (ignore if includeStandardLicenseTexts if false). If false, the standard license text will appear in each component section.
- NEW IN RELEASE 136 includeInnerSource: if true, InnerSource components will be included in the attribution report.
- NEW IN RELEASE 137 includeSonatypeSpecialLicenses: if true, Sonatype Special Licenses (e.g., Generic-Copyleft-Clause, Generic-Liberal-Clause, See-License-Clause, Identity-Clause, etc.) will be included in the attribution report.
Templates can be created, updated, and modified. When generating a report you may also pass in a template identifier to generate a report from the given template.
POST an Attribution Report Template (save or update)
Creating a new Attribution Report Template
To create a new AttributionReportTemplate you can issue a POST request to the following path:
POST /api/v2/licenseLegalMetadata/report-template
Body:
{
"templateName": "Unique Template name",
"documentTitle" : "Attribution Report Document title",
"header": "Legal Header 2021",
"footer": "Legal Footer 2021",
"includeTableOfContents": true,
"includeAppendix": false,
"includeStandardLicenseTexts": false,
"includeInnerSource": false,
"includeSonatypeSpecialLicenses": false
}The returned value will contain the id of template.
Updating an existing Attribution Report Template
The same POST method is used for updating an AttributionReportTemplate, but an id field must be given.
POST /api/v2/licenseLegalMetadata/report-template
Body:
{
"id": "1",
"templateName": "Unique Template name",
"documentTitle" : "Attribution Report Document title",
"header": "Legal Header 2021",
"footer": "Legal Footer 2021",
"includeTableOfContents": true,
"includeAppendix": false,
"includeStandardLicenseTexts": false,
"includeInnerSource": false,
"includeSonatypeSpecialLicenses": false
}GET all Attribution Report Templates
To fetch a list of all Attribution Report Template use the following path:
GET /api/v2/licenseLegalMetadata/report-template
GET an Attribution Report Template
To fetch a specific attribution template given it's id use the following path:
GET /api/v2/licenseLegalMetadata/report-template/{id}DELETE an Attribution Report Template
To delete a specific attribution template given it's id use the following path:
DELETE /api/v2/licenseLegalMetadata/report-template/{id}Legal Attribution Attribution Report HTML
GET default License Legal Application Attribution HTML Report By Stage
To generate the default HTML Attribution Report of an application you can issue a GET request to the following path
GET /api/v2/licenseLegalMetadata/application/{applicationPublicId}/stage/{stageId}/reportFor example, to get the license legal application report for an application with id "MyApp" at the "Release" stage you could issue this request
curl -u admin:admin123 http://localhost:8070/api/v2/licenseLegalMetadata/application/MyApp/stage/release/report
This cURL request will produce a HTML response containing the default Attribution Report.
GET Attribution Report by Stage and Template Id
NEW IN RELEASE 126
To generate an Attribution Report from an existing Attribution Report Template use the following path:
POST /api/v2/licenseLegalMetadata/application/{applicationPublicId}/stage/{stageId}/report/templateId/{templateId}
Content-type: "multipart/form-data"
noticeFiles=@linkToFileExample cUrl request:
curl -u admin:admin123 --request POST 'http://localhost:8070/api/v2/licenseLegalMetadata/application/myApp/stage/build/report/templateId/fooBar' \ --form 'noticeFiles=@"/path/to/file/NOTICE.txt"'
Get Attribution Report with custom fields
NEW IN RELEASE 126
To generate a custom Attribution Report use the following path:
POST /api/v2/licenseLegalMetadata/application/{applicationPublicId}/stage/{stageId}/report/templateId/{templateId}
Content-type: "multipart/form-data"
Form-data:
title=Document title
header=Optional header
footer=Optional Footer
includeToc=true
includeStandardLicenseTexts=true
includeAppendix=true
noticeFiles=@linkToFile
includeInnerSource=true
includeSonatypeSpecialLicenses=trueExample cUrl request:
curl -u admin:admin123 --request POST 'http://localhost:8070/api/v2/licenseLegalMetadata/application/myApp/stage/build/report/templateId/fooBar' \ --form 'title="My Report title"' \ --form 'header="My header"' \ --form 'footer="My footer"' \ --form 'includeToc="true"' \ --form 'includeStandardLicenseTexts="true"' \ --form 'includeAppendix="true"' \ --form 'noticeFiles=@"/path/to/file/NOTICE1.txt"' \ --form 'noticeFiles=@"/path/to/file/NOTICE2.txt"' \ --form 'includeInnerSource="true"' \ --form 'includeSonatypeSpecialLicenses="true"'
Note: Notice files must be of text/plain content type, any other content type is not supported.
Multiple applications, a single stage, no custom notice files, no template, include special sonatype licenses
NEW IN RELEASE 134
Response Times
The report generation time for Attribution Reports could be longer for a large no. of applications or components. We estimate a response time of 1 minute for generation of attribution reports for around 1000 components. For environments using reverse proxy, we recommend increasing the reverse proxy timeout to generate Attribution Reports for a large no. of applications or components.
To generate an Attribution Report with multiple app public ids and single stage id, use the following path:
POST /api/v2/licenseLegalMetadata/multiApplication/report Content-type: "multipart/form-data" Form-data: applications=Document applications stages=Document stages includeSonatypeSpecialLicenses=true
Example cUrl request:
curl -u admin:admin123 --request POST 'http://localhost:8070/api/v2/licenseLegalMetadata/multiApplication/report' \ --form 'applications="app1,app2"' \ --form 'stages="build"' \ --form 'includeSonatypeSpecialLicenses="true"'
Multiple applications, multiple stages, custom notice files, no template, customized fields, filter special sonatype licenses
NEW IN RELEASE 134
To generate an Attribution Report with multiple app public ids, multiple stages ids and custom notice files use the following path:
POST /api/v2/licenseLegalMetadata/customMultiApplication/report Content-type: "multipart/form-data" Form-data: applications=Document applications stages=Document stages noticeFiles=@linkToFile title=Document title header=Optional header footer=Optional Footer includeToc=true includeInnerSource=true includeSonatypeSpecialLicenses=false
Example cUrl request:
curl -u admin:admin123 --request POST 'http://localhost:8070/api/v2/licenseLegalMetadata/customMultiApplication/report' \ --form 'applications="app1,app2"' \ --form 'stages="build"' \ --form 'noticeFiles=@"/path/to/file/NOTICE1.txt"' \ --form 'title="My Report title"' \ --form 'header="My header"' \ --form 'footer="My footer"' \ --form 'includeToc="true"' \ --form 'includeInnerSource="true"' \ --form 'includeSonatypeSpecialLicenses="false"'
Multiple applications, multiple stages, custom notice files, with template
NEW IN RELEASE 134
To generate an Attribution Report with multiple app public ids, multiple stages ids with a template, use the following path:
POST /api/v2/licenseLegalMetadata/multiApplication/report/templateId/{templateId}
Content-type: "multipart/form-data"
Form-data:
applications=Document applications
stages=Document stages
noticeFiles=@linkToFileExample cUrl request:
curl -u admin:admin123 --request POST 'http://localhost:8070/api/v2/licenseLegalMetadata/multiApplication/report/templateId/{templateId}' \
--form 'applications="app1,app2"' \
--form 'stages="build"' \
--form 'noticeFiles=@"/path/to/file/NOTICE1.txt"' \GET a License Legal Component Report
To get a License Legal Component Report's raw data you can issue a GET request to the following path
GET /api/v2/licenseLegalMetadata/{organization|application}/{ownerId}/component?{componentIdentifier|packageUrl|hash}=...The specified organization or application will determine the license, copyright, notice files, license files, and attribution files overrides (if any). For example, if obligations are resolved at an Organization scope then all components under this Organization will contain these overriden values. Note that the Root Organization can also be specified via the organization id ROOT_ORGANIZATION_ID .
For example, to get the license legal component report for an application with id "MyApp" and a component with coordinates "org.apache.httpcomponents : httpclient : 4.1" and hash "93cd011acb220de08b57" you could issue any one of these requests.
curl -u admin:admin123 http://localhost:8070/api/v2/licenseLegalMetadata/application/MyApp/component?componentIdentifier={%22format%22:%22maven%22,%22coordinates%22:{%22artifactId%22:%22httpclient%22,%22classifier%22:%22%22,%22extension%22:%22jar%22,%22groupId%22:%22org.apache.httpcomponents%22,%22version%22:%224.1%22}}curl -u admin:admin123 http://localhost:8070/api/v2/licenseLegalMetadata/application/MyApp/component?packageUrl=pkg:maven/org.apache.httpcomponents/httpclient@4.1?type=jar
curl -u admin:admin123 http://localhost:8070/api/v2/licenseLegalMetadata/application/MyApp/component?hash=93cd011acb220de08b57
Note that only one of componentIdentifier , packageUrl , or hash , must be specified.
There are also two optional parameters, identificationSource specifying the component identification source, and scanId specifying the id for the report where the component was identified. Note that the latter is only used with a third party identification source.
For example, to get the license legal component report for an application with id "MyApp" and a component with coordinates "debian-9 : glibc : 2.24-11+deb9u3" identified by a third party scan with id "1c0af74bbbb4474e8b4ac417f94d2692", you could issue this request
curl -u admin:admin123 http://localhost:8070/api/v2/licenseLegalMetadata/application/MyApp/component?componentIdentifier={%22format%22:%22debian-9%22,%22coordinates%22:{%22name%22:%22glibc%22,%22version%22:%222.24-11+deb9u3%22}}&identificationSource=Clair&scanId=1c0af74bbbb4474e8b4ac417f94d2692The initial cURL request will produce a JSON response of the following form (some data has been omitted and/or abbreviated for brevity)
{
"component": {
"packageUrl": "pkg:maven/org.apache.httpcomponents/httpclient@4.1?type=jar",
"hash": "93cd011acb220de08b57",
"componentIdentifier": {
"format": "maven",
"coordinates": {
"artifactId": "httpclient",
"classifier": "",
"extension": "jar",
"groupId": "org.apache.httpcomponents",
"version": "4.1"
}
},
"displayName": "httpclient",
"licenseLegalData": {
"declaredLicenses": [
"See-License-Clause",
"Apache-UNSPECIFIED"
],
"observedLicenses": [
"Apache-2.0"
],
"effectiveLicenses": [
"See-License-Clause",
"Apache-2.0"
],
"highestEffectiveLicenseThreatGroup": "Liberal",
"copyrights": [
{
"id": null,
"content": "Copyright 2000-2010 Some Auther",
"originalContentHash": "sha256Hash",
"status": "enabled"
},
{
"id": 123,
"content": "Copyright 1999-2010 The Apache Software Foundation",
"originalContentHash": "sha256Hash",
"status": "disabled"
},
...
],
"licenseFiles": [
{
"id": null,
"relPath": "META-INF/LICENSE.txt",
"content": "license file 2 content",
"originalContentHash": "sha256Hash",
"status": "disabled"
},
...
],
"noticeFiles": [
{
"id": 2,
"relPath": "NOTICE.txt",
"content": "notice file 1 content",
"originalContentHash": "sha256Hash",
"status": "enabled"
},
...
],
"obligations": [
{
"name": "Existing Liability",
"status": "OPEN"
},
{
"name": "Inclusion of Copyright",
"status": "FULFILLED",
"comment": "obligation comment",
"ownerId": "ownerId",
"lastUpdatedAt": 1615407013073,
"lastUpdatedByUsername": "admin"
},
...
],
"sourceLinks": [
{
"id": null,
"sourceLink": "https://repo1.maven.org/maven2/org/apache/httpcomponents/httpclient/4.1/httpclient-4.1.jar",
"status": "enabled"
},
...
]
}
},
"licenseLegalMetadata": [
{
"licenseId": "Apache-UNSPECIFIED",
"licenseName": "Apache",
"licenseText": null,
"obligations": []
},
{
"licenseId": "Apache-2.0",
"licenseName": "Apache-2.0",
"licenseText": "Apache-2.0 Standard License Text content",
"obligations": [
{
"name": "Inclusion of License",
"obligationTexts": [
"You must give any other recipients of the Work or Derivative Works a copy of this License;"
]
},
...
],
"threatGroup": {
"name": "Liberal",
"threatLevel": 0
},
"isMulti": false
},
...
]
}| Item | Description |
|---|---|
| component | This is simply a container for the component information. It will always include the format and the coordinates. |
| format | This is the format the component is in, and will determine what type of coordinate information is displayed. |
| coordinates | This will depend on the format. An example would be Maven, which uses a G : A : E : C : V (Group, Artifact Id, Extension, Classifier, and Version) for the component. In this example, the fields provided are: component. |
| packageUrl | The package URL or purl of the component |
| hash | This is the hash value for the component. For example, in the case of Java components, this would be matched to a Java repository (e.g. Central). If you have proprietary components configured, it would be matched against your list of proprietary components. The returned hash value is truncated and is meant to be used as an identifier that can be passed into subsequent REST API calls. It is not intended to be used as a checksum. |
| componentIdentifier | The component identifier for the component including its format and coordinates |
| displayName | The display name for the component |
| licenseLegalData | The license legal data for the component including its licenses (declared, observed, effective), its effective license threats, its copyrights, and the content of its legal files (licenses and notices) |
| highestEffectiveLicenseThreatGroup | The highest LTG detected within this component. |
| licenseLegalData.copyrights | The list of all unique Copyrights detected within this component |
| licenseLegalData.licenseFiles | The list of all unique License files detected within this component. |
| licenseLegalData.noticeFiles | The list of all unqiue Notice files detected within this component. |
| licenseLegalData.sourceLinks | The list of source links for the current component. |
| originalContentHash | The sha256 of the original content value - a unique identifier for the content. If the original content hash is empty, it indicates a custom copyright/notice file/legal file; that is, the item was not discovered by the ALP. |
| status | Possible values are "enabled" or "disabled". Disabled items will not be show in the generated attribution report. |
| relPath | The relative path of the legal file from the root of the component. |
| comment | Any comments attached to this item. |
| ownerId | The owner identifier which represents the scope of this item. Can be either the Root Organization, an organization, or an application. |
| lastUpdatedAt | Timestamp of when this item was last updated. |
| lastUpdatedBy | Username of the person who last updated this item. |
| licenseLegalData.obligations | A list of legal obligations associated with this license. |
| licenseLegalData.obligations.name | The name of the legal obligations, can be cross-referenced from the licenseLegalMetadata's obligations. |
| licenseLegalData.obligations.status | Possible values are:
|
| licenseLegalMetadata | The license legal metadata for the component including, for each of its effective licenses, the license id, the license name, the license text, and the license obligations. This object is used as a dictionary for legal data within the application's components. |
| licenseLegalMetadata.licenseText | The full standard license text of the license. |
| licenseLegalMetadata.obligations.obligationTexts | The obligation text from the license text which led to the discovery of the obligation. |
| licenseLegalMetadata.threatGroup.name | The LTG name of the license. |
| licenseLegalMetadata.threatGoup.threatLeval | The LTG threat level for this license. |
| licenseLegalMetadata.isMulti | True if this license contains multiple licenses, false otherwise. |
NEW IN RELEASE 114
New REST endpoint /api/v2/licenseLegalMetadata/application/{applicationPublicId}/stage/{stageId}
NEW IN RELEASE 126
New REST endpoint GET|POST /api/v2/licenseLegalMetadata/report-template
New REST endpoint GET|DELETE /api/v2/licenseLegalMetadata/report-template/{id}
New REST endpoint POST /api/v2/licenseLegalMetadata/application/{applicationPublicId}/stage/{stageId}/report (Previously only GET)
NEW IN RELEASE 134
New REST endpoint POST /api/v2/licenseLegalMetadata/customMultiApplication/report
New REST endpoint POST /api/v2/licenseLegalMetadata/multiApplication/report
New REST endpoint POST /api/v2/licenseLegalMetadata/multiApplication/report/templateId/{templateId}
NEW IN RELEASE 137
Modified REST endpoint POST /api/v2/licenseLegalMetadata/{applicationPublicId}/stage/{stageId}/report to accept includeSonatypeSpecialLicenses form parameter
Modified REST endpoint POST /api/v2/customMultiApplication/report to accept includeSonatypeSpecialLicenses form parameter
Modified REST endpoint POST /api/v2/multiApplication/activeUserFilter/report to accept includeSonatypeSpecialLicenses form parameter