# Protocol

> **Package : spaceone.api.notification.v1**

## Protocol

{% hint style="info" %}
**Protocol Methods:**
{% endhint %}

| NO | Method                               | Request Type                                                | Response Type                                                                                                      | Description                                                                                                                                                                                                                                                                                    |
| -- | ------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1  | [**create**](#create)                | [CreateProtocolRequest](#createprotocolrequest)             | [ProtocolInfo](#protocolinfo)                                                                                      | Creates a new Protocol.Protocol is the definition of which method to use when dispatching the Notifications through a Channel.When creating a protocol, you must specify the plugins provided from the repository, and you must also set the credentials to be set in the plugin if necessary. |
| 2  | [**update**](#update)                | [UpdateProtocolRequest](#updateprotocolrequest)             | [ProtocolInfo](#protocolinfo)                                                                                      | Updates a Protocol information.Update methods can update name, tags only. If you want to update plugin version or options, you can use update\_plugin method.                                                                                                                                  |
| 3  | [**update\_plugin**](#update_plugin) | [UpdateProtocolPluginRequest](#updateprotocolpluginrequest) | [ProtocolInfo](#protocolinfo)                                                                                      | Updates a plugin for Protocol.This method is usually used when redeploying a deployed plugin container to a new version.                                                                                                                                                                       |
| 4  | [**enable**](#enable)                | [ProtocolRequest](#protocolrequest)                         | [ProtocolInfo](#protocolinfo)                                                                                      | Enables a Protocol.If the disabled Protocol is enabled, the Protocol can be used again and the notification can be dispatched.                                                                                                                                                                 |
| 5  | [**disable**](#disable)              | [ProtocolRequest](#protocolrequest)                         | [ProtocolInfo](#protocolinfo)                                                                                      | Disables a Protocol.If you disable the Protocol, the notification will not be dispatched, even if they are created.                                                                                                                                                                            |
| 6  | [**delete**](#delete)                | [ProtocolRequest](#protocolrequest)                         | [google.protobuf.Empty](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/empty.proto)   | Delete the protocol.If there is even one channel using the protocol, it cannot be deleted.                                                                                                                                                                                                     |
| 7  | [**get**](#get)                      | [GetProtocolRequest](#getprotocolrequest)                   | [ProtocolInfo](#protocolinfo)                                                                                      | Gets a single Protocol.                                                                                                                                                                                                                                                                        |
| 8  | [**list**](#list)                    | [ProtocolQuery](#protocolquery)                             | [ProtocolsInfo](#protocolsinfo)                                                                                    | Lists the specified Protocols.Can search information using the query format provided by SpaceONE.Detailed information about Query format can be checked in the Search Query pages.                                                                                                             |
| 9  | [**stat**](#stat)                    | [ProtocolStatQuery](#protocolstatquery)                     | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) |                                                                                                                                                                                                                                                                                                |

### create

> **POST** /notification/v1/protocols
>
> Creates a new Protocol.Protocol is the definition of which method to use when dispatching the Notifications through a Channel.When creating a protocol, you must specify the plugins provided from the repository, and you must also set the credentials to be set in the plugin if necessary.

| Type     | Message                                         |
| -------- | ----------------------------------------------- |
| Request  | [CreateProtocolRequest](#createprotocolrequest) |
| Response | [ProtocolInfo](#protocolinfo)                   |

### update

> **PUT** /notification/v1/protocol/{protocol\_id}
>
> Updates a Protocol information.Update methods can update name, tags only. If you want to update plugin version or options, you can use update\_plugin method.

| Type     | Message                                         |
| -------- | ----------------------------------------------- |
| Request  | [UpdateProtocolRequest](#updateprotocolrequest) |
| Response | [ProtocolInfo](#protocolinfo)                   |

### update\_plugin

> **PUT** /notification/v1/protocol/{protocol\_id}/plugin
>
> Updates a plugin for Protocol.This method is usually used when redeploying a deployed plugin container to a new version.

| Type     | Message                                                     |
| -------- | ----------------------------------------------------------- |
| Request  | [UpdateProtocolPluginRequest](#updateprotocolpluginrequest) |
| Response | [ProtocolInfo](#protocolinfo)                               |

### enable

> **PUT** /notification/v1/protocol/{protocol\_id}/enable
>
> Enables a Protocol.If the disabled Protocol is enabled, the Protocol can be used again and the notification can be dispatched.

| Type     | Message                             |
| -------- | ----------------------------------- |
| Request  | [ProtocolRequest](#protocolrequest) |
| Response | [ProtocolInfo](#protocolinfo)       |

### disable

> **PUT** /notification/v1/protocol/{protocol\_id}/disable
>
> Disables a Protocol.If you disable the Protocol, the notification will not be dispatched, even if they are created.

| Type     | Message                             |
| -------- | ----------------------------------- |
| Request  | [ProtocolRequest](#protocolrequest) |
| Response | [ProtocolInfo](#protocolinfo)       |

### delete

> **DELETE** /notification/v1/protocol/{protocol\_id}
>
> Delete the protocol.If there is even one channel using the protocol, it cannot be deleted.

| Type     | Message                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------- |
| Request  | [ProtocolRequest](#protocolrequest)                                                                              |
| Response | [google.protobuf.Empty](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/empty.proto) |

### get

> **GET** /notification/v1/protocol/{protocol\_id}
>
> Gets a single Protocol.

| Type     | Message                                   |
| -------- | ----------------------------------------- |
| Request  | [GetProtocolRequest](#getprotocolrequest) |
| Response | [ProtocolInfo](#protocolinfo)             |

### list

> **GET** /notification/v1/protocols
>
> **POST** /notification/v1/protocols/search
>
> Lists the specified Protocols.Can search information using the query format provided by SpaceONE.Detailed information about Query format can be checked in the Search Query pages.

| Type     | Message                         |
| -------- | ------------------------------- |
| Request  | [ProtocolQuery](#protocolquery) |
| Response | [ProtocolsInfo](#protocolsinfo) |

### stat

> **POST** /notification/v1/protocols/stat

| Type     | Message                                                                                                            |
| -------- | ------------------------------------------------------------------------------------------------------------------ |
| Request  | [ProtocolStatQuery](#protocolstatquery)                                                                            |
| Response | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) |

## Message

### CreateProtocolRequest

| No | Field        | Type                                                                                                               | Required | Description                                                                                            |
| -- | ------------ | ------------------------------------------------------------------------------------------------------------------ | :------: | ------------------------------------------------------------------------------------------------------ |
| 1  | name         | string                                                                                                             |     ✅    | The name of Protocol. It can have a maximum of 255 characters.                                         |
| 2  | plugin\_info | [PluginRequest](#pluginrequest)                                                                                    |     ✅    | Describe a Plugin information for protocol that include was used plugin, specific version, schema etc. |
| 3  | tags         | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) |     ❌    | The tags for protocol.                                                                                 |
| 4  | domain\_id   | string                                                                                                             |     ✅    | The ID of domain to which the Protocol belongs.                                                        |

### GetProtocolRequest

| No | Field        | Type           | Required | Description                                                                                                    |
| -- | ------------ | -------------- | :------: | -------------------------------------------------------------------------------------------------------------- |
| 1  | protocol\_id | string         |     ✅    | The ID of Protocol.                                                                                            |
| 2  | domain\_id   | string         |     ✅    | The ID of domain to which the Protocol belongs.                                                                |
| 3  | only         | list of string |     ❌    | The list of the Protocol information column you want to be returned. It must be specified in the ProtocolInfo. |

### PluginInfo

| No | Field         | Type                                                                                                               | Description                                                                                                                                                                         |
| -- | ------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1  | plugin\_id    | string                                                                                                             | The ID of plugin set in the Protocol.                                                                                                                                               |
| 2  | version       | string                                                                                                             | The version of plugin.                                                                                                                                                              |
| 3  | options       | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) | The Options that contains information about using plugin.                                                                                                                           |
| 4  | secret\_id    | string                                                                                                             | The ID of the Secret containing encrypted data to be used in the plugin.                                                                                                            |
| 5  | metadata      | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) | The metadata of plugin. It includes schema for the data that must be set for the Channel when creating the Channel using a Protocol.The schema follows the JSON Schema format.      |
| 6  | upgrade\_mode | <ul><li>NONE</li><li>AUTO</li><li>MANUAL</li></ul>                                                                 | Auto upgrade for plugin.If the upgrade\_mode is AUTO, check the latest plugin version when running the plugin, and if a new version is existed, replace the plugin and then run it. |

### PluginRequest

| No | Field         | Type                                                                                                               | Required | Description                                                                                                                                                                                |
| -- | ------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1  | plugin\_id    | string                                                                                                             | ✅        | The ID of plugin.                                                                                                                                                                          |
| 2  | version       | string                                                                                                             | ✅        | The version of plugin.                                                                                                                                                                     |
| 3  | options       | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) | ❌        | The Options that contains information about using plugin.                                                                                                                                  |
| 4  | secret\_data  | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) | ❌        | The data for using plugin if necessary. This data is encrypted and stored in the Secret service.                                                                                           |
| 5  | schema        | string                                                                                                             | ✅        | The name of schema.When the secret\_data is stored in the Secret service, it can be set with schema if the schema is existed.The schema is provided through the Repository service.        |
| 6  | upgrade\_mode | <ul><li>NONE</li><li>AUTO</li><li>MANUAL</li></ul>                                                                 | ✅        | Auto upgrade feature for plugin.If the upgrade mode is AUTO, check the latest plugin version when running the plugin, and if a new version is existed, replace the plugin and then run it. |

### ProtocolInfo

| No | Field          | Type                                                                                                               | Description                                                                                 |
| -- | -------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| 1  | protocol\_id   | string                                                                                                             | The ID of Protocol.                                                                         |
| 2  | name           | string                                                                                                             | The name of Protocol.                                                                       |
| 3  | state          | <ul><li>NONE</li><li>ENABLED</li><li>DISABLED</li></ul>                                                            | The state of Protocol.ENABLED or DISABLED only.                                             |
| 4  | protocol\_type | <ul><li>PROTOCOL\_TYPE\_NONE</li><li>INTERNAL</li><li>EXTERNAL</li></ul>                                           | {}                                                                                          |
| 5  | resource\_type | string                                                                                                             | Resource type for Protocol. Currently only identity.Project or identity.User can be set.    |
| 6  | capability     | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) | The capability information for the Protocol. It included supported schema for the Protocol. |
| 7  | plugin\_info   | [PluginInfo](#plugininfo)                                                                                          | the plugin information set in Protocol.                                                     |
| 8  | tags           | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) | The tags for protocol.                                                                      |
| 9  | domain\_id     | string                                                                                                             | The ID of domain to which the Protocol belongs.                                             |
| 10 | created\_at    | string                                                                                                             | Protocol creation time.                                                                     |

### ProtocolQuery

| No | Field          | Type                                                                                               | Required | Description                                                                    |
| -- | -------------- | -------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| 1  | query          | [spaceone.api.core.v1.Query](https://spaceone-dev.gitbook.io/api-reference/common-v1/search-query) | ❌        | Query format provided by SpaceONE. Please check the link for more information. |
| 2  | protocol\_id   | string                                                                                             | ❌        | The ID of Protocol.                                                            |
| 3  | name           | string                                                                                             | ❌        | The name of Protocol.                                                          |
| 4  | state          | <ul><li>NONE</li><li>ENABLED</li><li>DISABLED</li></ul>                                            | ❌        | The state of Protocol. ENABLED or DISABLED only.                               |
| 5  | protocol\_type | <ul><li>PROTOCOL\_TYPE\_NONE</li><li>INTERNAL</li><li>EXTERNAL</li></ul>                           | ❌        | The type of Protocol. INTERNAL or EXTERNAL only.                               |
| 6  | domain\_id     | string                                                                                             | ✅        | The ID of domain to which the Protocol belongs.                                |

### ProtocolRequest

| No | Field        | Type   | Required | Description                                     |
| -- | ------------ | ------ | :------: | ----------------------------------------------- |
| 1  | protocol\_id | string |     ✅    | The ID of Protocol.                             |
| 2  | domain\_id   | string |     ✅    | The ID of domain to which the Protocol belongs. |

### ProtocolStatQuery

| No | Field      | Type                                                                                                             | Required | Description                                                                               |
| -- | ---------- | ---------------------------------------------------------------------------------------------------------------- | :------: | ----------------------------------------------------------------------------------------- |
| 1  | query      | [spaceone.api.core.v1.StatisticsQuery](https://spaceone-dev.gitbook.io/api-reference/common-v1/statistics-query) |     ✅    | Statistics Query format provided by SpaceONE. Please check the link for more information. |
| 2  | domain\_id | string                                                                                                           |     ✅    | The ID of domain to which the Protocol belongs.                                           |

### ProtocolsInfo

| No | Field        | Type                                                                                            | Description                        |
| -- | ------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------- |
| 1  | results      | [list of ProtocolInfo](#protocolinfo)                                                           | List of queried protocols.         |
| 2  | total\_count | [int32](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/type.proto) | Total counts of queried Protocols. |

### UpdateProtocolPluginRequest

| No | Field        | Type                                                                                                               | Required | Description                                                                                                                          |
| -- | ------------ | ------------------------------------------------------------------------------------------------------------------ | :------: | ------------------------------------------------------------------------------------------------------------------------------------ |
| 1  | protocol\_id | string                                                                                                             |     ✅    | The ID of Protocol.                                                                                                                  |
| 2  | version      | string                                                                                                             |     ❌    | The version of plugin you want to update. Version means the tags of plugin container image in repository that specific market place. |
| 3  | options      | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) |     ❌    | The Options that contains information about using plugin.                                                                            |
| 4  | domain\_id   | string                                                                                                             |     ✅    | The ID of domain to which the Protocol belongs.                                                                                      |

### UpdateProtocolRequest

| No | Field        | Type                                                                                                               | Required | Description                                                                                                 |
| -- | ------------ | ------------------------------------------------------------------------------------------------------------------ | :------: | ----------------------------------------------------------------------------------------------------------- |
| 1  | protocol\_id | string                                                                                                             |     ✅    | The ID of Protocol.                                                                                         |
| 2  | name         | string                                                                                                             |     ❌    | The Name of Protocol. It can have a maximum of 255 characters.                                              |
| 3  | tags         | [google.protobuf.Struct](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/struct.proto) |     ❌    | The tags for protocol. When updating, existing tag information is deleted all and will be updated with new. |
| 4  | domain\_id   | string                                                                                                             |     ✅    | The ID of domain to which the Protocol belongs.                                                             |
