# License Legal REST API

This endpoint is only available with the [Advanced Legal Pack](https://help.sonatype.com/en/add-on-packs.html "Add-on Packs").

## License Legal Application Report Raw Data

This section of endpoints returns the raw JSON legal data for an application.

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

The legal attribution HTML report can be generated from a template. The template allows the following fields to be configured:

- documentTitle: The title is displayed at the top of the attribution report.
- header: _Optional_ header which will be displayed at the top of the attribution report above the title.
- footer: _Optional_footer displayed at the bottom of the report.
- includeTableOfContents: if true a table of contents containing links to components and their licenses will be added to the report.
- includeStandardLicenseTexts: if true, the standard license text will be displayed for components with no License files.
- includeAppendix: if true, the standard license text will be grouped in the report appendix (ignore if includeStandardLicenseTexts if false). If false, the standard license text will appear in each component section.
- includeInnerSource: if true, [InnerSource components](https://help.sonatype.com/en/innersource-insight.html "InnerSource Insight") will be included in the attribution report.
- includeSonatypeSpecialLicenses: if true, SonatypeSpecial 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 the 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 Templates use the following path:

```
GET /api/v2/licenseLegalMetadata/report-template
```

### GET an Attribution Report Template

To fetch a specific attribution template given its ID, use the following path:

```
GET /api/v2/licenseLegalMetadata/report-template/{id}
```

### DELETE an Attribution Report Template

To delete a specific attribution template given its 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 an HTML response containing the default Attribution Report.

### GET Attribution Report by Stage and Template Id

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

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

**Note**

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 the generation of attribution reports for around 1000 components. For environments using a 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

To generate an Attribution Report with multiple app public ids, multiplestages 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

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:
appplications=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=%7B%22format%22%3A%22maven%22%2C%22coordinates%22%3A%7B%22artifactId%22%3A%22httpclient%22%2C%22classifier%22%3A%22%22%2C%22extension%22%3A%22jar%22%2C%22groupId%22%3A%22org.apache.httpcomponents%22%2C%22version%22%3A%224.1%22%7D%7D"
```

```
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\
        },\
        ...\
    ]
}
```