debian-mirror-gitlab/doc/api/templates/licenses.md

169 lines
5.4 KiB
Markdown
Raw Normal View History

2019-12-04 20:38:33 +05:30
---
type: reference
---
2017-09-10 17:25:29 +05:30
# Licenses API
2016-06-02 11:05:42 +05:30
2019-12-04 20:38:33 +05:30
In GitLab, there is an API endpoint available for working with various open
source license templates. For more information on the terms of various
licenses, see [this site](https://choosealicense.com/) or any of the many other
resources available online.
2016-06-02 11:05:42 +05:30
## List license templates
Get all license templates.
```
2016-11-03 12:29:30 +05:30
GET /templates/licenses
2016-06-02 11:05:42 +05:30
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `popular` | boolean | no | If passed, returns only popular licenses |
```bash
2017-08-17 22:00:37 +05:30
curl https://gitlab.example.com/api/v4/templates/licenses?popular=1
2016-06-02 11:05:42 +05:30
```
Example response:
```json
[
{
"key": "apache-2.0",
"name": "Apache License 2.0",
"nickname": null,
"featured": true,
"html_url": "http://choosealicense.com/licenses/apache-2.0/",
"source_url": "http://www.apache.org/licenses/LICENSE-2.0.html",
"description": "A permissive license that also provides an express grant of patent rights from contributors to users.",
"conditions": [
"include-copyright",
"document-changes"
],
"permissions": [
"commercial-use",
"modifications",
"distribution",
"patent-use",
"private-use"
],
"limitations": [
"trademark-use",
"no-liability"
],
"content": " Apache License\n Version 2.0, January 2004\n [...]"
},
{
"key": "gpl-3.0",
"name": "GNU General Public License v3.0",
"nickname": "GNU GPLv3",
"featured": true,
"html_url": "http://choosealicense.com/licenses/gpl-3.0/",
"source_url": "http://www.gnu.org/licenses/gpl-3.0.txt",
"description": "The GNU GPL is the most widely used free software license and has a strong copyleft requirement. When distributing derived works, the source code of the work must be made available under the same license.",
"conditions": [
"include-copyright",
"document-changes",
"disclose-source",
"same-license"
],
"permissions": [
"commercial-use",
"modifications",
"distribution",
"patent-use",
"private-use"
],
"limitations": [
"no-liability"
],
"content": " GNU GENERAL PUBLIC LICENSE\n Version 3, 29 June 2007\n [...]"
},
{
"key": "mit",
"name": "MIT License",
"nickname": null,
"featured": true,
"html_url": "http://choosealicense.com/licenses/mit/",
"source_url": "http://opensource.org/licenses/MIT",
"description": "A permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty.",
"conditions": [
"include-copyright"
],
"permissions": [
"commercial-use",
"modifications",
"distribution",
"private-use"
],
"limitations": [
"no-liability"
],
"content": "The MIT License (MIT)\n\nCopyright (c) [year] [fullname]\n [...]"
}
]
```
## Single license template
Get a single license template. You can pass parameters to replace the license
placeholder.
```
2016-11-03 12:29:30 +05:30
GET /templates/licenses/:key
2016-06-02 11:05:42 +05:30
```
| Attribute | Type | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `key` | string | yes | The key of the license template |
| `project` | string | no | The copyrighted project name |
| `fullname` | string | no | The full-name of the copyright holder |
>**Note:**
If you omit the `fullname` parameter but authenticate your request, the name of
the authenticated user will be used to replace the copyright holder placeholder.
```bash
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/templates/licenses/mit?project=My+Cool+Project
2016-06-02 11:05:42 +05:30
```
Example response:
```json
{
"key": "mit",
"name": "MIT License",
"nickname": null,
"featured": true,
"html_url": "http://choosealicense.com/licenses/mit/",
"source_url": "http://opensource.org/licenses/MIT",
"description": "A permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty.",
"conditions": [
"include-copyright"
],
"permissions": [
"commercial-use",
"modifications",
"distribution",
"private-use"
],
"limitations": [
"no-liability"
],
"content": "The MIT License (MIT)\n\nCopyright (c) 2016 John Doe\n [...]"
}
```
2019-12-04 20:38:33 +05:30
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->