screwdriver-api/plugins/templates/README.md

API server for the Screwdriver.cd service

# Templates Plugin
> Hapi templates plugin for the Screwdriver API

## Usage

### Register plugin

```javascript
const Hapi = require('@hapi/hapi');
const server = new Hapi.Server();
const templatesPlugin = require('./');

server.connection({ port: 3000 });

server.register({
    register: templatesPlugin,
    options: {}
}, () => {
    server.start((err) => {
        if (err) {
            throw err;
        }
        console.log('Server running at:', server.info.uri);
    });
});
```

### Routes

#### Template
##### Get all templates

`GET /templates`

Can filter by template namespace:
`GET /templates?namespace=chef`

Can search by keyword in template name, namespace, and description:
`GET /templates?search=screwdriver`

Can list all distinct template namespaces:
`GET /templates?distinct=namespace`

Can use additional options for sorting, pagination and get total count:
`GET /templates?sort=ascending&sortBy=name&page=1&count=50&getCount=true`

##### Get a single template

You can get a single template by providing the template name and the specific version or the tag.

`GET /templates/{name}/{tag}` or `GET /templates/{name}/{version}`

###### Arguments

'name', 'tag' or 'version'

* `name` - Name of the template
* `tag` - Tag of the template (e.g. `stable`, `latest`, etc)
* `version` - Version of the template

##### Get a single template using templateId

You can get a single template by providing the template id.

`GET /templates/{id}`

###### Arguments

'id'

* `id` - Id of the template

##### Create a template
Creating a template will store the template data (`config`, `name`, `version`, `description`, `maintainer`) into the datastore.

`version` will be auto-bumped. For example, if `mytemplate@1.0.0` already exists and the version passed in is `1.0.0`, the newly created template will be version `1.0.1`.

*Note: This endpoint is only accessible in `build` scope and the permission is tied to the pipeline that first creates the template.*

`POST /templates`

###### Arguments

'name', 'namespace', 'version', 'description', 'maintainer', 'labels'

* `name` - Name of the template
* `namespace` - (Optional) Namespace of the template
* `version` - Version of the template
* `description` - Description of the template
* `maintainer` - Maintainer of the template
* `labels` - Labels of the template. This field is optional and should be an array.
* `config` - Config of the template. This field is an object that includes `steps`, `image`, and optional `secrets`, `environments`. Similar to what's inside the `job`

Example payload:
```json
{
  "name": "build",
  "namespace": "screwdriver",
  "labels": ["stable"],
  "version": "1.7.3",
  "description": "this is a template",
  "maintainer": "foo@bar.com",
  "config": {
      "steps": [{
          "echo": "echo hello"
      }]
  }
}
```

##### Delete a template
Deleting a template will delete a template and all of its associated tags and versions.

`DELETE /templates/{name}`

###### Arguments

* `name` - Name of the template

##### Delete a version

Delete the template version and all of its associated tags.
If the deleted version was the last published, the API would set the `latest` attribute of the previous version to `true`.

`DELETE /templates/{name}/versions/{version}`

###### Arguments

'name', 'version'

* `name` - Name of the template
* `version` - Version of the template

##### Get Report of Pipelines that use a template version

`GET /templates/{name}/{version}/usage/pipelines`


###### Arguments

'name', 'version'

* `name` - Name of the template
* `version` - Version of the template

###### Example response

```json
[
    {
        id: 4,
        name: 'nathom/sd-uses-template',
        scmRepo: {
          branch: 'main',
          name: 'nathom/sd-uses-template',
          url: 'https://github.com/nathom/sd-uses-template/tree/main/pipe2',
          rootDir: 'pipe2',
          private: false
        },
        lastRun: '2023-07-31T17:15:37.510Z',
        admins: { nathom: true }
    },
]
```

#### Template Tag
Template tag allows fetching on template version by tag. For example, tag `mytemplate@1.1.0` as `stable`.

##### Create/Update a tag

If the template tag already exists, it will update the tag with the new version. If the template tag doesn't exist yet, this endpoint will create the tag.

*Note: This endpoint is only accessible in `build` scope and the permission is tied to the pipeline that creates the template.*

`PUT /templates/{templateName}/tags/{tagName}` with the following payload

* `version` - Exact version of the template (ex: `1.1.0`)

##### Delete a tag

Delete the template tag. This does not delete the template itself.

*Note: This endpoint is only accessible in `build` scope and the permission is tied to the pipeline that creates the template.*

`DELETE /templates/{templateName}/tags/{tagName}`