Postman is an invaluable tool that helps developers design, document and test API's. We use it at Shotstack for testing endpoints. We also use it for designing, developing and testing JSON video edits.
We have created a public team and shared a large collection of JSON templates to the Postman web site. You can post the JSON templates to the API to render a video. You can use the collection to learn more about Shotstack and how it works. You can also use the examples as starting points for your own template designs.
You can view the Shotstack workspace on the Postman web site. The web site allows you to view and copy/paste JSON but you can not send requests from public collections. In order to send requests you will need to fork the Edit API collection. This guide will take you step by step through the process.
In this example we used the desktop client but the steps below will also work in the browser.
Once installed and logged in you should see a welcome screen like below:
Because you can not send requests in public collections we will need to create our own copy. Copying a collection is called forking (just like a Git repo).
First, search for
shotstack in the search bar in the top center of the screen. In the results, click on the Shotstack text with a team icon (two heads) next to it:
The Shotstack team page will open showing our latest collections and workspace. The workspace contains one or more collections. We currently have 2 collections but in this guide we will only use the Edit API collection.
Click on Edit API under Latest collections section:
Click the fork icon as shown in the screenshot below:
Then fill out the form by entering a new name for the collection. Under Location chose My Workspace:
Once the collection is forked you should see all the available requests, organized in folders down the left hand side:
To send requests to the Shotstack API you will need to have an account and an API key. Each request needs to have the API key added to a header variable called
x-api-key. Below we'll step through how to use the staging key and environment with Postman.
First, click on the eye icon next to the No Environment drop down and click Add:
The environment editor tab will open. You need to give the environment a name, we use
Shotstack Stage Environment and then fill in Current and Initial values for the
SHOTSTACK_API_KEY variable and enter
stage for the
ENV variable. See below how these variables are set up, including the API key:
Save and exit the environment config tab and make sure
Shotstack Stage Environment is selected from the dropdown list.
With the collection forked and our credentials added it is time to start making requests. There is a wide range of examples and templates that you can run and learn from.
A good example to start with is in the Basic Edits folder, called Basic Edit (Title, Image, Video). Open the folder and click on the request name, a tab will open up defaulting to the Params section:
The next section is the Authorization section. Authorization is already configured to use the API key you added to the environment. It sets the
x-api-key header using the
SHOTSTACK_API_KEY environment variable. This section is the same for every request and does not need to be changed:
This simply handles the response from the Shotstack API and sets an environment variable
RENDER_ID with the ID in the response. This ID will be used later when we check the render status. This is all set up for you and you do not need to make any changes:
Finally, the Body section includes the JSON video edit. This is the description of the edit, the content and sequence of clips and assets. You can play modify the JSON to create a new video if you wish:
Click on Send when you are ready to create a video. Postman will send the JSON to the API with the API key and you will receive a response from the API like below:
When the response is received the
RENDER_ID variable is populated ready to use in the Get status request. This endpoint is all set up, ready to use. Scroll to the bottom of the list on the left hand side and click on the Get status request.
Click Send to fetch the status of the video render. The response will give you the
status of the render task. If
done, a video
url parameter will also be shown. If the video is still rendering, wait 10 seconds and try again:
In the get status response, you should see a
response.url value. You can click on the URL and a new tab will open with the URL in the Request url field. Click Send and the video will download, once downloaded, the video can be played:
The collection contains examples on how to style text with HTML, position elements in the viewport, effects, transitions and filters. There are also some complete templates that you can copy and modify for your own applications.
We test and create new templates all the time so will keep adding new examples which will update in realtime in your Postman software.