Unsplash Bridge

This repository contains Cloudflare Worker that picks photos from Unsplash collections via Unsplash API.

Cloudflare Workers are like serverless cloud functions, but they also can cache stuff in Cloudflare CDN to make things faster. If you are not familiar with Cloudflare Workers, visit Cloudflare Workers documentation. Or you can just press the button instead:

Motivation

This is a bridge to Unsplash Image API which respects Unsplash API Guidelines.

Current implementation solves following problems:

• Hides Unsplash API Access Key on server side, so you don't need to pass access key to your client-side application, which is not secure and forbidden by Unsplash API Guidelines.
• Automatically notifies Unsplash about photo downloads, which is also mandatory by Unsplash. It means when a photo is picked or used for something, you should notify Unsplash about this. The worker handles this automatically. See "Guideline: Triggering a Download" for more details.

It was developed to be used for Camellia needs, so the current subset of features is pretty limited.

API

The bridge exposes following endpoints:

GET /random-collection-entry

Returns random photo from passed Unsplash collection.

It also notifies Unsplash about downloads. See "Guideline: Triggering a Download" for more details.

A response is cached on clients for 12 hours with Cache-Control header.

It accepts following query-parameters:

• id — collection ID.

Example:

GET https://your-worker-name.workers.dev/random-collection-entry?id=123

Returns following JSON in response:

{
  "image": {
    "url": "https://images.unsplash.com/photo-1634482895955-712847090dfd?crop=entropy&cs=tinysrgb&fm=jpg&ixid=MnwxNDQwNjN8MHwxfHJhbmRvbXx8fHx8fHx8fDE2NjA4NTA5OTc&ixlib=rb-1.2.1&q=80",
    "resolution": {
      "width": 3591,
      "height": 2394
    }
  },
  "photographer": {
    "name": "Nick Night",
    "url": "https://unsplash.com/@lvenfoto",
    "avatar": {
      "small": {
        "url": "https://images.unsplash.com/profile-1575888295849-0025f8946dfcimage?ixlib=rb-1.2.1&crop=faces&fit=crop&w=32&h=32",
        "resolution": {
          "width": 32,
          "height": 32
        }
      },
      "medium": {
        "url": "https://images.unsplash.com/profile-1575888295849-0025f8946dfcimage?ixlib=rb-1.2.1&crop=faces&fit=crop&w=64&h=64",
        "resolution": {
          "width": 64,
          "height": 64
        }
      },
      "large": {
        "url": "https://images.unsplash.com/profile-1575888295849-0025f8946dfcimage?ixlib=rb-1.2.1&crop=faces&fit=crop&w=128&h=128",
        "resolution": {
          "width": 128,
          "height": 128
        }
      }
    }
  },
  "webPageUrl": "https://unsplash.com/photos/y3sKIJqiY40"
}

Developing the worker

Clone the repository. Then, install dependencies:

npm ci

Start webpack:

webpack watch

Open another terminal and then run the worker in development mode:

wrangler dev