License Legal REST API - v2

NEW IN RELEASE 113

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 explination 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}/report

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/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=@linkToFile

Example 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=true

Example 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


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=@linkToFile

Example 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=1c0af74bbbb4474e8b4ac417f94d2692

The 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
        },
        ...
    ]
}
ItemDescription
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.

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

componentIdentifierThe component identifier for the component including its format and coordinates
displayNameThe display name for the component
licenseLegalDataThe 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)
highestEffectiveLicenseThreatGroupThe highest LTG detected within this component.
licenseLegalData.copyrightsThe list of all unique Copyrights detected within this component
licenseLegalData.licenseFilesThe list of all unique License files detected within this component.
licenseLegalData.noticeFilesThe list of all unqiue Notice files detected within this component.
licenseLegalData.sourceLinksThe list of source links for the current component.
originalContentHashThe 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.
statusPossible values are "enabled" or "disabled".  Disabled items will not be show in the generated attribution report.
relPathThe relative path of the legal file from the root of the component.
commentAny comments attached to this item.
ownerIdThe owner identifier which represents the scope of this item. Can be either the Root Organization, an organization, or an application.
lastUpdatedAtTimestamp of when this item was last updated.
lastUpdatedByUsername of the person who last updated this item.
licenseLegalData.obligationsA list of legal obligations associated with this license.
licenseLegalData.obligations.nameThe name of the legal obligations, can be cross-referenced from the licenseLegalMetadata's obligations.
licenseLegalData.obligations.status

Possible values are:

  • OPEN: the obligation has not beed addressed.
  • IGNORED: the obligation is not relevant.
  • FLAGGED: the obligation required further investigation.
  • FULFILLED: the obligation has been fulfilled.
licenseLegalMetadataThe 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.licenseTextThe full standard license text of the license.
licenseLegalMetadata.obligations.obligationTextsThe obligation text from the license text which led to the discovery of the obligation.
licenseLegalMetadata.threatGroup.nameThe LTG name of the license.
licenseLegalMetadata.threatGoup.threatLevalThe LTG threat level for this license.
licenseLegalMetadata.isMultiTrue 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