Overview

In this tutorial, we will be creating simple example of a common upload userflow whereby a user is created and media is uploaded to Olapic.

For Olapic APIv2’s full technical specs, please refer to the APIv2 documentation.

Full Code

You can view the full code for this tutorial here.

Authentication

API Key

To make valid API calls, you will need your Olapic API Key.
You can find your API Key in the Olapic Platform by clicking the Settings icon in the top right corner:
Copy the API key by clicking the COPY button:

Dependencies

For this exercise, we will be using following libraries:

jQuery to handle DOM manipulation and AJAX call to the Olapic API jQuery from Google CDN
Dropzone for drag-and-drop upload functionality Dropzone Github

Setup

We’ll create a page that will contains all of our HTML. Our <head> section will contain links to our stylesheets, JavaScript files and any dependencies. Here is what it looks like so far:

<head>

 <title>Olapic API Examples - Upload Example</title>

 <link rel="stylesheet" type="text/css" href="css/main.css">
 <link rel="stylesheet" href="css/dropzone.min.css">

 <!-- jQuery -->
 <script src="https://code.jquery.com/jquery-3.2.1.min.js" integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4=" crossorigin="anonymous"></script>

 <!-- Dropzone -->
 <script src="js/dropzone.min.js"></script>

 <!-- main JS with API calls to Olapic -->
 <script src="js/upload.js"></script>

 </head>

The <body> of our page will contain the structure for three steps, through which users will be able to upload their photos to an Olapic account.

A simple user creation form that collects the user’s name and email
A drag-and-drop file uploader
A thank you message and UGC preview

<body>
	<div class="upload-form-container">
		<!-- Step 1: Get a user's name and email -->
		<div data-step="1" class="step active">
			<form action="/" method="post" id="user-registration">
				<label for="screen_name">Name</label>
				<input type="text" name="screen_name" id="screen_name" required>
					<label for="email">Email</label>
					<input type="email" name="email" id="email" required>
						<button type="button" class="next">Next</button>
					</form>
				</div>
				<!-- Step 2: Upload a photo -->
				<div data-step="2" class="step">
					<form action="/" class="dropzone" id="uploader"></form>
					<button type="button" class="next">Submit photo</button>
				</div>
				<!-- Step 3: Display a "thank you" message -->
				<div data-step="3" class="step">
					<h4>Thanks!</h4>
					<p>Your photo has been submitted. If approved, your media will be used in widgets throughout our site.</p>
				</div>
			</div>
		</body>

We’ll also need to create a upload.js file to execute our JavaScript. Let’s begin with the following:

// The API Key from the Authorization section above

 var authToken = "<insert your copied API key>";

 // we'll replace olapicUser with the created user, which we'll use in the upload function later.
var olapicUser = false;

 // For our drag-and-drop uploader, we want to disable auto discover so we can instantiate it with some custom settings. 
Dropzone.autoDiscover = false;

Creating a user in Olapic

All media uploaded to Olapic needs to be attached to a user. When collected through social media, the screen name of the original poster is used. In the case of an upload, though, we ask for the user’s name and email as required fields. Optionally, a user can also have an avatar image, which we display in the standard Olapic widgets.

In order to create a user, we need a basic HTML form with:

A text input for the user’s name (or screen name)
An email input for the user’s email address
An AJAX function that creates the new user with the Olapic API

We’ve already covered the first two requirements in our above HTML. As for the AJAX call to create a new user, we can use the following:

function createUser() {
	var screen_name = $('input[name="screen_name"]').val(),
		email = $('input[name="email"]').val(); // basic validation of screen name and email address
	if (screen_name.length > 1 && /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/.test(email.toLowerCase())) {
		return $.ajax({
			// Endpoint to create a user
			url: "https://photorankapi-a.akamaihd.net/users?version=v2.2&auth_token=" + authToken,
			method: "post",
			processData: false,
			contentType: false,
			// Get form data 
			data: new FormData($('#user-registration')[0]),
			dataType: "json",
			success: function(res) {
				if (res.metadata.code == 200) {
					// set our scoped olapicUser to the ID returned by the API
					olapicUser = res.data.id;
					return true;
				} else {
					console.log(res)
				}
			},
			error: function(err) {
				console.log(err)
			}
		});
	}
	return false;
}

The above script will create a user in Olapic and return the created user object. For upload purposes, only the user’s ID is required so we store that in a variable to be used by the upload function.

Note: If a user with the designated email already exists, that user object will be returned in the API response body.

Uploading media

There are two ways to upload media into Olapic. The first is to upload the media directly from form data (i.e., a file input). The second is to first stash the media in Olapic, then reference the stashed media object in the upload function, thereby attaching it to a specific user. The second method is useful if you intend to collect media before creating a user in your flow, and the related API endpoints can be found here. Since we’ve already created a user, we’ll be following the first method.

// instantiate our drag-and-drop uploader
var uploader = new Dropzone("#uploader", {
	autoProcessQueue: false,
	maxFiles: 1
});
// function to upload UGC to Olapic
function uploadPhoto() {
	if (uploader.files.length === 0) return false;
	// get the uploaded file, attach it to our FormData 
	var file = uploader.files[0];
	var fd = new FormData();
	fd.append('file', file);
	// Upload media to Olapic 
	return $.ajax({
		url: "https://photorankapi-a.akamaihd.net/users/" + olapicUser + "/media?version=v2.2&auth_token=" + authToken,
		method: "post",
		processData: false,
		contentType: false,
		data: fd,
		success: function(res) {
			if (res.metadata.code == 200) {
				$('.step[data-step="3"]').append('<div class="preview"><img src="' + res.data.images.mobile + '" /></div>');
				return true;
			} else {
				console.log(res)
			}
		},
		error: function(err) {
			console.log(err)
		}
	});
}

The above function will upload media to Olapic and return the created media object. A response code of 200 indicates a successful upload, and the response body has all of the properties of an Olapic media. Of particular interest is the images property, which contains the size variations of the uploaded media.

{
	"metadata": {
		"code": 200,
		"message": "OK",
		"version": "v2.0"
	},
	"data": {
		"_links": {
			"self": {
				"href": "//photorankapi-a.akamaihd.net/media/3650439857?auth_token=f76f475cb0ba23392ff342baf95f0c88cd9f9d6cee87e0a8801ad69301b34b9f&version=v2.2"
			}
		},
		"id": "3650439857",
		"_fixed": true,
		"type": "IMAGE",
		"date_submitted": "2020-08-21T19:16:40+00:00",
		"status": "pending",
		// ...
		"images": {
			"square": "https://z2photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/square.jpg",
			"thumbnail": "https://z2photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/thumbnail.jpg",
			"mobile": "https://photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/mobile.jpg",
			"normal": "https://photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/normal.jpg",
			"original": "https://z1photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/original"
		}
		// ...
	}
} {
	"metadata": {
		"code": 200,
		"message": "OK",
		"version": "v2.0"
	},
	"data": {
		"_links": {
			"self": {
				"href": "//photorankapi-a.akamaihd.net/media/3650439857?auth_token=f76f475cb0ba23392ff342baf95f0c88cd9f9d6cee87e0a8801ad69301b34b9f&version=v2.2"
			}
		},
		"id": "3650439857",
		"_fixed": true,
		"type": "IMAGE",
		"date_submitted": "2020-08-21T19:16:40+00:00",
		"status": "pending",
		// ...
		"images": {
			"square": "https://z2photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/square.jpg",
			"thumbnail": "https://z2photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/thumbnail.jpg",
			"mobile": "https://photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/mobile.jpg",
			"normal": "https://photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/normal.jpg",
			"original": "https://z1photorankmedia-a.akamaihd.net/media/n/q/v/nqv6bu4/original"
		}
		// ...
	}
}

Bringing it together

Since the goal is a step-by-step upload flow where we create a user first, then upload media for that user, then display a thank you message with a preview of the media, we’ll need some logic to manage the progression. For our example, we’ll listen for a click event on our next buttons, perform a required function for each step (e.g., register user, upload media), and progress the user to the next step.

$('.next').click(function() {
	var currentStep = $(this).closest('.step').data('step');
	if (currentStep == 1) {
		var valid = createUser();
	} else if (currentStep == 2) {
		var valid = uploadPhoto();
	}
	if (valid) {
		$('.active').removeClass('active');
		$('.step[data-step="' + (currentStep + 1) + '"]').addClass('active')
	} else {
		alert('Please ensure all fields are filled out correctly.')
	}
})

And that’s it! You now have a working UGC uploader.