Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/kuzzleio/kuzzle-plugin-cloudinary

Manage your images with Cloudinary
https://github.com/kuzzleio/kuzzle-plugin-cloudinary
cloudinary cloudinary-api kuzzle kuzzle-plugin
Last synced: about 2 months ago
JSON representation
Manage your images with Cloudinary
Host: GitHub
URL: https://github.com/kuzzleio/kuzzle-plugin-cloudinary
Owner: kuzzleio
License: apache-2.0
Created: 2019-06-06T14:10:24.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2021-06-07T14:43:50.000Z (over 3 years ago)
Last Synced: 2024-06-23T12:44:52.470Z (3 months ago)
Topics: cloudinary, cloudinary-api, kuzzle, kuzzle-plugin
Language: JavaScript
Homepage:
Size: 357 KB
Stars: 0
Watchers: 10
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        


  



# Kuzzle Plugin : Cloudinary

Cloudinary is cloud-based image and video management platform. It automates the entire image-processing pipeline: from uploads to on-the-fly manipulations to optimization to dynamic delivery with any CDN.

This plugin will let you use some of Cloudinary API's functions within Kuzzle. 

You can test this plugin with Swagger UI. Find more in the [Testing section](#testing)

***This plugin is available for 1.8.2 and higher version of Kuzzle***

## Compatibility matrice

| Kuzzle Version | Plugin Version |

| -------------- | -------------- |

| 1.x.x          | 1.x.x          | 

| 2.x.x          | 2.x.x          | 

## Usage

 

Here are the existing routes (Note that all of these are preceded by `http://:/_plugin/cloudinary`) 

| HTTP Verb | Route |Description | 

| :---- | :---- | :---- | 

| POST | [/assets/search](#search-function) | Searches for some assets corresponding to an expression | 

| POST | [/assets/transform](#transform-function)  | Returns the url of an asset with some transformation |

| PUT | [/assets/](#rename-function)  | Renames an asset |

| DELETE | [/assets/](#destroy-function)  | Deletes an asset |

| POST | [/tags/](#add_tag-function)  | Adds a tag to one or many assets | 

| PUT | [/tags/](#replace_tag-function)  | Replaces all the tags from one or many assets by another tag |

| DELETE | [/tags/](#remove_tag-function)  | Deletes a tag from one or many assets | 

| DELETE | [/tags/remove_all](#remove_all_tags-function)  | Deletes all the tags from one or many assets | 

### Assets controller

#### `search` function

This function searches for assets corresponding to the given expression

You can use the cloudinary **search function** by sending a `POST` HTTP-request to this route : `http://:/_plugin/cloudinary/assets/search`

The expression must be a descriptive string of your research. For more informations on the syntax of this string, check the [Cloudinary documentation about Expressions][cloudinary expression doc]

##### Request format 

```js

{

  "controller": "cloudinary/assets",

  "action": "search",

  "expression": "",

  "max_results": "",

  "next_cursor": "",

  "with_field": [ "" ],

  "sort_by": [  ["",""] ]

}

```

**You must provide, at least, either the `expression` or the `next_cursor` field. If both are set, `expression` will be ignored** 

You can find more info [here](https://cloudinary.com/documentation/search_api#parameters)

##### Response format 

```js

{

  "status": 200,

  "error": null,

  "controller": "cloudinary/assets",

  "action": "destroy",

  "requestId": "",

  "result": {

      "total_count": "",

      "time": "",

      "next_cursor": "",

      "resources" : [ 

          {

              "public_id": "",

              "folder": "",

              "filename": "",

              "format": "",

              "resource_type": "",

              "type": "",

              "created_at": "",

              "bytes": "",

              "backup_bytes": 0,

              "width": "",

              "height": "",

              "aspect_ratio": "",

              "pixels": "",

              "url": "",

              "secure_url": "",

              "status": "",

              "access_mode": "",

          }

      ],

      "rate_limit_allowed": "",

      "rate_limit_reset_at": "",

      "rate_limit_remaining": ""

      

  }

}

```

For more information on search response, see [Cloudinary documentation](https://cloudinary.com/documentation/search_api#response)

#### `transform` function

This function returns an url to access the given asset with the given transformations

You can use the **transform function** by sending a `POST` HTTP-request to this route : 

`http://:/_plugin/cloudinary/assets/transform`

##### Request format 

```js

{

  "controller": "cloudinary/assets",

  "action": "transform",

	"public_id" : "sample", 

	"transformation" : {

		"width" : 400,

		"radius" : "100:0:100:100"

	}

}

```

The request body must contain the following properties : 

| Property         | Type   | Description                                   |

| ---------------- | ------ | --------------------------------------------- |

| `public_id` | string | public_id of the file to be transformed |

| `transformation`   | JSON | a json describing all the transformations you want to apply to the asset. See [Cloudinary transformation guides][cloudinary transformation doc]     |

##### Response format 

```js

{

  "status": 200,

  "error": null,

  "controller": "cloudinary/assets",

  "action": "transform",

  "requestId": "",

  "result": ""

}

```

#### `rename` function 

This function renames the given asset

You can use the cloudinary **rename function** by sending a `PUT` HTTP-request to this route : `http://:/_plugin/cloudinary/assets/`

:warning: Be aware that Cloudinary allows special characters in the public_id syntax. You may need to encode the public id with escape character

##### Request format 

```js

{

  "controller": "cloudinary/assets",

  "action": "rename",

  "public_id": "old_name",

  "new_public_id": "new_name"

}

```

The request must contain the following properties : 

| Property         | Type   | Description                                   |

| ---------------- | ------ | --------------------------------------------- |

| `public_id` | string | public_id of the file to be renamed |

| `new_public_id`   | string | new public_id of the file           |

##### Response format 

```js

{

  "status": 200,

  "error": null,

  "controller": "cloudinary/assets",

  "action": "destroy",

  "requestId": "",

  "result": {

      "public_id": "",

      "width": "",

      "height": "",

      "format": "",

      "resource_type": "",

      "created_at": "",

      "tags": [

          ""

      ],

      "bytes": "",

      "type": "",

      "placeholder": "",

      "url": "",

      "secure_url": ""

  }

}

```

#### `destroy` function 

This function deletes the given asset

You can use the cloudinary **destroy function** by sending a `DELETE` HTTP-request to this route : `http://:/_plugin/cloudinary/assets/`

:warning: Be aware that Cloudinary allows special characters in the public_id syntax. You may need to encode the public id with escape character

##### Request format

```js

{

  "controller": "cloudinary/assets",

  "action": "destroy",

  "public_id": "sample"

}

```

The request must contain the following properties : 

| Property         | Type   | Description                                   |

| ---------------- | ------ | --------------------------------------------- |

|`public_id`|string|public_id of the file to be deleted|

##### Response format 

```js

{

  "status": 200,

  "error": null,

  "controller": "cloudinary/assets",

  "action": "destroy",

  "requestId": "",

  "result": {

      "result": "ok"

  }

}

```

### Tags controller

#### `add_tag` function 

This function adds the given tag to the given assets

You can use the cloudinary **add_tag function** by sending a `POST` HTTP-request to this route : `http://:/_plugin/cloudinary/tags/`

##### Request format

```js

{

  "controller": "cloudinary/tags",

  "action": "addTag",

	"public_id" : [ "sample", "sample2" ], 

	"tag" : ""

}

```

The request must contain the following properties : 

| Property         | Type   | Description                                   |

| ---------------- | ------ | --------------------------------------------- |

|`public_id`|string or [string]|the public_id of the asset to be edited. 
 **Can concern many assets if you use an array of strings !** 
*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |

|`tag`|string| the tag to be added |

For more information see the [Cloudinary tags methods][cloudinary tags doc]

##### Response format 

```js

{

  "status": 200,

  "error": null,

  "controller": "cloudinary/tags",

  "action": "addTag",

  "requestId": "",

  "result": {

      "public_ids": [

          "sample",

          "sample2"

      ] 

  }

}

```

#### `replace_tag` function 

This function replace all the current tag of the given assets by the given tag

You can use the cloudinary **replace_tag function** by sending a `PUT` HTTP-request to this route : `http://:/_plugin/cloudinary/tags/`

##### Request format 

```js

{

  "controller": "cloudinary/tags",

  "action": "replaceTag",

  "public_id" : [ "sample", "sample2" ],

  "tag": "a_tag"

}

```

The request must contain the following properties : 

| Property         | Type   | Description                                   |

| ---------------- | ------ | --------------------------------------------- |

|`public_id`|string or [string]|the public_id of the asset to be edited. 
 **Can concern many assets if you use an array of strings !** 
*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |

|`tag`|string| the tag that will replace all the current tag|

For more information see the [Cloudinary tags methods][cloudinary tags doc]

##### Response format 

```js

{

    "status": 200,

    "error": null,

    "controller": "cloudinary/tags",

    "action": "replaceTag",

    "requestId": "",

    "result": {

        "public_ids": [

            "sample",

            "sample2"

        ] 

    }

}

```

#### `remove_tag` function

This function removes the given tag from the given assets 

You can use the cloudinary **remove_tag function** by sending a `DELETE` HTTP-request to this route : `http://:/_plugin/cloudinary/tags/`

##### Request format 

```js

{

    "controller": "cloudinary/tags",

    "action": "removeTag",

	"public_id" : [ "sample", "sample2" ],

    "tag": "a_tag"

}

```

The request must contain the following properties : 

| Property         | Type   | Description                                   |

| ---------------- | ------ | --------------------------------------------- |

|`public_id`|string or [string]|the public_id of the asset to be edited. 
 **Can concern many assets if you use an array of strings !** 
*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |

|`tag`|string| the tag to be removed |

For more information see the [Cloudinary tags methods][cloudinary tags doc]

##### Response format 

```js

{

    "status": 200,

    "error": null,

    "controller": "cloudinary/tags",

    "action": "removeTag",

    "requestId": "",

    "result": {

        "public_ids": [

            "sample",

            "sample2"

        ] 

    }

}

```

#### `remove_all_tags` function 

This function removes all tags from the given assets

You can use the cloudinary **remove_all_tags function** by sending a `DELETE` HTTP-request to this route : `http://:/_plugin/cloudinary/tags/remove_all`

##### Request format 

```js

{

    "controller": "cloudinary/tags",

    "action": "removeAllTags",

	"public_id" : [ "sample", "sample2" ] 

}

```

The request must contain the following properties : 

| Property         | Type   | Description                                   |

| ---------------- | ------ | --------------------------------------------- |

|`public_id`|string or [string]|the public_id of the asset to be edited. 
 **Can concern many assets if you use an array of strings !** 
*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |

For more information see the [Cloudinary tags methods][cloudinary tags doc]

##### Response format 

```js

{

    "status": 200,

    "error": null,

    "controller": "cloudinary/tags",

    "action": "removeAllTags",

    "requestId": "",

    "result": {

        "public_ids": [

            "sample",

            "sample2"

        ] 

    }

}

```

## Error handling 

All tag methods can throw a `206 PartialError` if at least one resource has not been updated : This error will contain all the errors encountered during the request. 

## Configuration 

In order to use this plugin, you **need to provide your Cloudinary credentials** in the Vault.

Here is the template of the needed structure :

```json 

{

  "cloudinary": {

    "APIKey":  "your-cloudinary-api-key",

    "APISecret": "your-cloudinary-api-secret",

    "cloudName": "your-cloudinary-cloudname"

  }

}

```

You can find more about Vault feature on the [Kuzzle documentation][kuzzle vault doc]

## Installation 

### On your Kuzzle Stack

Clone this repository in your `plugin/available` directory, install all needed modules with `npm install` and then link this directory to your `plugin/enabled` directory. 

```bash 

git clone https://github.com/kuzzleio/kuzzle-plugin-cloudinary.git /path-of-your-kuzzle/plugins/available cloudinary

cd /path-of-your-kuzzle/plugins/available/cloudinary/

npm install 

ln -sr ./ ../../plugins/enabled/cloudinary 

```

You can now restart Kuzzle and check [http://localhost:7512](http://localhost:7512), you should see the plugin name under the key `serverInfo.kuzzle.plugins.cloudinary`.

## Testing 

If you want to test this plugin, you can use the [Swagger UI online tool](https://petstore.swagger.io)

1) Run Kuzzle with the plugin installed (See [Installation section](#Installation)) **Make sure it is correctly [configured](#Configuration) with your Cloudinary credentials**

2) Go on the [Swagger UI online tool](https://petstore.swagger.io)

3) Enter the following link `https://raw.githubusercontent.com/kuzzleio/kuzzle-plugin-cloudinary/master/test/swagger-spec.yaml` and click `Explore`

4) You have now the details of all available requests, and you can try these out.

[cloudinary tags doc]: https://cloudinary.com/documentation/image_upload_api_reference#tags_method

[cloudinary expression doc]: https://cloudinary.com/documentation/search_api#expressions

[cloudinary transformation doc]: https://cloudinary.com/documentation/image_transformation_reference

[kuzzle vault doc]: https://docs.kuzzle.io/core/2/guides/essentials/secrets-vault/