{"id":25343,"date":"2022-10-17T07:30:00","date_gmt":"2022-10-17T14:30:00","guid":{"rendered":"https:\/\/cloudinary.com\/blog\/?p=25343"},"modified":"2024-05-24T16:21:32","modified_gmt":"2024-05-24T23:21:32","slug":"send-api-requests-with-ease-using-cloudinary-postman-collections","status":"publish","type":"post","link":"https:\/\/cloudinary.com\/blog\/send-api-requests-with-ease-using-cloudinary-postman-collections","title":{"rendered":"Send API Requests with Ease Using Cloudinary Postman Collections"},"content":{"rendered":"\n

Sending API requests to Cloudinary is the bare minimum required to unleash all your media potential. It happens all the time. You\u2019ve sent multiple API requests to Cloudinary just by loading this blog post (or at least your browser has). Loading media in your browser is as simple as a get request to an image or video URL and our URL API returns you exactly what you\u2019re after.<\/p>\n\n\n\n

Uploading and managing your media is a little more complex though, and understandably, has additional barriers such as authentication. You can handle all of this using one of our many SDKs, or you can make use of our Command Line Interface<\/a>, but what about if you just want to try out a few requests without having to write code or install the CLI? This is where Postman comes in. Postman is the number one tool for helping developers build out and test REST APIs, be it your own or, in this case, Cloudinary\u2019s.\u00a0<\/p>\n\n\n\n

Postman comes with a comprehensive set of features, designed to help you easily send API requests to a number of different services with only minimal setup. Start simple by sending a few requests to get an idea about the API and the responses you might get back, before progressing to using it for scheduling tasks, running complex workflows, or including it in a CI pipeline.<\/p>\n\n\n\n

This blog post will introduce you to the Cloudinary Postman collections and show you how to make use of a variety of features Postman has to offer.<\/p>\n\n\n\n

To help you follow along with the examples in this blog post, we\u2019ve created a Cloudinary Examples<\/a> collection that includes a set of folders and requests which you can view and optionally fork.<\/p>\n\n\n\n

Introducing the Cloudinary Postman Collections<\/h2>\n\n\n\n

Before digging into some examples and use cases, get familiar with the Cloudinary Postman collections. They are designed to provide example requests for all of our API endpoints and with just a few setup steps are ready for you to update with your own credentials and parameter values. The Programmable Media collections are located in a dedicated public Postman Workspace<\/a> and are split up by API.<\/p>\n\n\n\n

\"\"\/<\/figure>\n\n\n\n

Sending Your First Requests<\/h2>\n\n\n\n

Before you can start sending your first requests, you\u2019ll need to get yourself set up with the collections. We have an in-depth guide for this in our documentation<\/a>, but we will run through the steps below.<\/p>\n\n\n\n

Create a Postman account<\/h3>\n\n\n\n

If you don\u2019t already have a Postman account, you\u2019ll need to sign up<\/a> for a new account in order to fork the collections.<\/p>\n\n\n\n

Set up your environment<\/h3>\n\n\n\n

Your Postman environment allows you to define a set of variables that can be used across multiple requests. For the Cloudinary Collections, use the environment to set your account credentials. You can find the Cloudinary environment included with the Cloudinary Collections, you can fork this to your workspace and then set your credentials.<\/p>\n\n\n\n

Fork the relevant collections<\/h3>\n\n\n\n

Head to the Programmable Media public Postman Workspace<\/a> and find the collection\/collections you want to start using. You\u2019ll need to fork each one to your own workspace before you can start updating parameters and sending requests.<\/p>\n\n\n\n

Run a collection<\/h3>\n\n\n\n

The Cloudinary collections can be run with minimal adjustments to the parameters and values. Most collections will include placeholder values. In some cases, these values will need to be updated to use valid values for your account and media assets.<\/p>\n\n\n\n

After making sure that all required parameter variables have valid values, click the Run button to send your request and view the response.<\/p>\n\n\n\n

For requests made to the Upload API, the Cloudinary Postman collections have a pre-request script<\/a> that runs before the request is made. This script handles the signature generation, which is required to be able to send a direct request to the API, making it super simple and intuitive.<\/p>\n\n\n\n

You can find an example of a signed upload request in the \u201cUploading\u201d folder of the Cloudinary Examples<\/a> collection. The pre-request script is included with the request so you can see how this works and experiment easily with uploading to your Cloudinary account using Postman.<\/p>\n\n\n\n

Combining Requests Together<\/h2>\n\n\n\n

Running single requests is a great way to learn and understand how the Cloudinary APIs<\/a> work, but what if you wanted to accomplish a simple workflow involving your media using Postman. Thankfully, Postman has some great features that allow you to achieve this with some basic scripts. The Postman Runner is one such feature, allowing you to run a set of requests from a collection as a sequence.<\/p>\n\n\n\n

An example of this would be to search for a set of assets based on their size and the date they were uploaded and then generate a zip archive of these old images.<\/p>\n\n\n\n

Take a look at the \u201csearch and generate archive\u201d folder in the Cloudinary Examples<\/a> collection, here you will find two requests. One uses the search API to retrieve a list of all image assets smaller than 5MB that were uploaded over two years ago. The results are also restricted to a maximum of 5 and sorted in order of when they were created, starting with the oldest.<\/p>\n\n\n\n

The code for this is:<\/p>\n\n\n

{\n   \"expression\"<\/span>: \"uploaded_at<720d AND resource_type:image AND bytes<5000000\"<\/span>,\n   \"sort_by\"<\/span>: [{\"created_at\"<\/span>: \"asc\"<\/span>}],\n   \"max_results\"<\/span>: 5<\/span>\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n<\/div>\n\n\n
You\u2019ll notice there\u2019s also a \u201ctest\u201d configured for that request which takes the response and stores the public_ids in a collection variable as an array:<\/p>\n\n\n
const<\/span> jsonData = JSON<\/span>.parse(responseBody);\nconst<\/span> publicIds = []\n \njsonData.resources.forEach(resource<\/span> =><\/span> publicIds.push(resource.public_id));\npm.collectionVariables.set(\"public_ids\"<\/span>, publicIds)\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n<\/div>\n\n\n
This data is then pulled in by a \u201cPre-request Script\u201d for the second request which uses the generate_archive method of the upload API to create a zip archive of all the images that were identified using the search. In the example, we\u2019re also adding a transformation that applies an old-fashioned-looking filter.<\/p>\n\n\n
const<\/span> publicIds = pm.collectionVariables.get(\"public_ids\"<\/span>);\n \npublicIds.forEach(pids<\/span> =><\/span> {\n   pm.request.body.formdata.add({\n   key<\/span>: 'public_ids[]'<\/span>,\n   value<\/span>: pids\n});\n})\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n<\/div>\n\n
Note:<\/strong> 
As this request is a signed request using the upload API, the code to generate the signature is also included in the pre-request script. This is the same script that is set for all the example requests provided in the Upload API collection.<\/p>\n<\/div>\n\n\n
Scheduling routine jobs<\/h3>\n\n\n\n
Now that we have a collection that can be run using the runner, this can be configured to run on a schedule. The Postman feature for this is called Monitors<\/a>. <\/p>\n\n\n\n
You might want to tweak the above example to instead delete the large assets that were uploaded over two years ago. The \u201cSearch and delete\u201d folder of the Cloudinary Examples<\/a> collection demonstrates this. Using the requests in this folder, you could create a new Monitor and set the frequency to run once a week. Now, each week you\u2019ll receive an email notification with a summary of the requests that were run and you\u2019ll be able to keep a track of the media assets that were cleaned up.<\/p>\n\n\n
Notes<\/strong>