Pixomatix-Api

Pixomatix-Api is a Photo Gallery API powered by Ruby on Rails (4.2.1). It supports recursive scanning, thumbnail generation and resizing images to fit HDTV screens.

Demo : api.pixomatix.com

Front End Implementations

• AngularJS : Pixomatix-Angular (Demo)

Contents

• Configuration
  • App Configuration
  • AWS Configuration
• Rake Tasks
• API
  • API Guidelines
  • API Endpoints
    • Authentication
    • Images
• Credits
• About Me
• License

Configuration ↑

App Configuration ↑

Config File : config/pixomatix.yml

default: &default
  thumbnail_width: 200
  thumbnail_height: 200
  hdtv_height: 1080
  image_cache_dir: 'public/cache/' # relative path inside Rails.root
  image_prefix: 'KSC' # Image name prefix used for renaming images if opted
  thumbnail_path_regex: !ruby/regexp /(^[0-9]+)_([0-9]+)x([0-9]+)\.([a-z0-9]+)/i
  hdtv_path_regex: !ruby/regexp /(^[0-9]+)_([0-9]+)\.([a-z0-9]+)/i
  use_aws: false # If AWS is to be used for images. See config/aws.yml for configuration.

development:
  <<: *default
  image_root: ['/path/to/your/pics/dir/', '/vacation/pics/'] # Can be multiple directories with sub-directories
  use_aws: false

test:
  <<: *default
  image_root: []

stage:
  <<: *default
  image_root: []

production:
  <<: *default
  image_root: []

AWS Configuration ↑

Config File: config/aws.yml

default: &default
  access_key_id: 'AWS S3 Access Key'
  secret_access_key: 'AWS S3 Secret'
  region: 'S3 Region code from http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region'
  s3_bucket: 'AWS S3 Bucket Name'

development:
  <<: *default

test:
  <<: *default

stage:
  <<: *default

production:
  <<: *default

Rake Tasks ↑

Rename Images

WARNING: Make sure you have a backup of your images before doing this. There is absolutely no guarantee it'll work as expected.

Running this task is completely optional.

You can rename images in a directory in a continuous sequence with filesnames like PREFIX_YYYYMMDD_HHMMSS_NNNN.jpg where NNNN is zero padded sequence, time is taken from Image's EXIF data and PREFIX is as set in config/pixomatix.yml.

rake pixomatix:rename_images

Populate Images

Recursively scan image_root directories specified in config/pixomatix.yml and populate database.

rake pixomatix:populate_images

Generate Thumbnails

Generate thumbnails for all the populated images as per the specifications mentioned in config/pixomatix.yml. It won't generate thumbnails which exist already.

rake pixomatix:generate_thumbnails

Generate HDTV Images

Generate HDTV images by scaling images (preserving aspect ratio) as per HDTV height mentioned in config/pixomatix.yml. It'll also skip images which already have generated HDTV images.

rake pixomatix:generate_hdtv_images

Optimize Cache

Reclaim disk space by removing thumbnails/HDTV images which are no longer required.

rake pixomatix:optimize_cache

Sync Thumbnails To AWS S3

Sync generated thumbnails to AWS S3

rake pixomatix:sync_thumbnails

Sync HDTV Images To AWS S3

Sync generated HDTV images to AWS S3

rake pixomatix:sync_hdtv_images

Sync Everything To AWS S3

This is basically a combined task for above mentioned two AWS S3 sync tasks. It'll sync thumbnails and HDTV images to AWS S3.

rake pixomatix:aws_sync

API ↑

API URL : http://api.pixomatix.com/

API Version : v1 (default)

General Guidelines for API Usage ↑

Response format is always JSON whether you specify it or not. Following fields should not be passed via GET/POST parameters and must be passed on via HTTP headers only.

• API version using HTTP header as Accept: application/vnd.pixomatix.v1.
• Authentication token as X-Access-Token: 3086ed853a7336bc33c29e0dd674535c.
• User email as X-Access-Email: test@example.com. Can be passed as POST parameters only when registering a new user.
• Locale as Accept-Language: en-US.
• Reset password token as X-Access-Reset-Password-Token: 3086ed853a7336bc33c29e0dd674535c.
• Unlock token as X-Access-Unlock-Token: 3086ed853a7336bc33c29e0dd674535c.
• Confirmation token as X-Access-Confirmation-Token: 3086ed853a7336bc33c29e0dd674535c.
• Response format as Content-Type: application/json.

API Endpoints ↑

Authentication ↑

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/user
• GET /api/auth/validate
• DELETE /api/auth/logout
• GET /api/auth/reset_password
• POST /api/auth/reset_password
• GET /api/auth/unlock
• POST /api/auth/unlock
• GET /api/auth/confirm
• POST /api/auth/confirm
• PUT /api/users
• PATCH /api/users
• DELETE /api/users

Images ↑

• GET /api/galleries
• GET /api/galleries/:id
• GET /api/galleries/:id/photos
• GET /api/galleries/:id/galleries
• GET /api/galleries/:id/photo
• GET /api/galleries/:id/parent

Authentication API ↑

Register a new user : POST /api/auth/register ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -d '{"user":{"email":"test@example.com","password":"1234568","password_confirmation":"1234568","name":"Kulbir Saini"}}' \
     -X POST http://api.pixomatix.com/api/auth/register

Response when registered successfully

{"user":{"name":"Kulbir Saini","email":"test@example.com"},"notice":"User registered successfully"}
Response Code: 200

Response when registered already but not confimred yet

{"notice":"User already registered but not confirmed. Check your email to confirm account"}
Response Code: 401

Otherwise

{"error":["Password confirmation doesn't match Password", ...],"notice":"User registration failed"}
Response Code: 422

Login : POST /api/auth/login ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -d '{"user":{"email":"test@example.com","password":"1234568"}}' \
     -X POST http://api.pixomatix.com/api/auth/login

Response when user is locked

{"notice":"User account is locked","location":"/api/auth/unlock"}
Response Code: 401

Response when user not confirmed

{"notice":"User account is not confimred. Please check confirmation email for instructions","location":"/api/auth/login"}
Response Code: 401

Response when invalid email or password

{"notice":"Invalid email or password"}
Response Code: 401

Response when login successful

{"user":{"name":"Kulbir Saini","email":"test@example.com"},"token":"5a0dd200dccc9a87f83fcad30e1ae78b","notice":"Logged in successfully"}
Response Code: 200

Get current user : GET /api/auth/user ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Token: 5a0dd200dccc9a87f83fcad30e1ae78b' \
     -H 'X-Access-Email: test@example.com' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/auth/user

Validate authentication token : GET /api/auth/validate ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Token: 5a0dd200dccc9a87f83fcad30e1ae78b' \
     -H 'X-Access-Email: test@example.com' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/auth/validate

Logout user : DELETE /api/auth/logout ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Token: 5a0dd200dccc9a87f83fcad30e1ae78b' \
     -H 'X-Access-Email: test@example.com' \
     -w '\nResponse Code: %{http_code}\n' \
     -X DELETE http://api.pixomatix.com/api/auth/logout

Get reset password instructions : GET /api/auth/reset_password ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/auth/reset_password

Reset password using issued token : POST /api/auth/reset_password ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -H 'X-Access-Reset-Password-Token: 31b4aa71ea72c8ae3d9a37245e8569f1' \
     -w '\nResponse Code: %{http_code}\n' \
     -d '{"user":{"password":"1234568","password_confirmation":"1234568"}}' \
     -X POST http://api.pixomatix.com/api/auth/reset_password

Get unlock instructions : GET /api/auth/unlock ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/auth/unlock

Unlock user using issued token : POST /api/auth/unlock ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -H 'X-Access-Unlock-Token: 14fa864af566d03e7a35ef6c6e1e4bcf' \
     -w '\nResponse Code: %{http_code}\n' \
     -X POST http://api.pixomatix.com/api/auth/unlock

Get confirmation instructions : GET /api/auth/confirm ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/auth/confirm

Confirm account using issued token : POST /api/auth/confirm ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -H 'X-Access-Confirmation-Token: f5884aec88d513c2b3b2ef16b41210b8' \
     -w '\nResponse Code: %{http_code}\n' \
     -X POST http://api.pixomatix.com/api/auth/confirm

Update user data : PUT /api/users OR PATCH /api/users ↑ API

WARNING: Email can not be updated.

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -H 'X-Access-Token: a4c4e6734f5050e6460ed91c608fc147' \
     -w '\nResponse Code: %{http_code}\n' \
     -d '{"user":{"password":"1234568","password_confirmation":"1234568","name":"Yo Test!"}}' \
     -X PUT http://api.pixomatix.com/api/users

Cancel registration : DELETE /api/users ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -H 'X-Access-Email: test@example.com' \
     -H 'X-Access-Token: ff7c0ee84d6b08c2edfd1938776865cc' \
     -w '\nResponse Code: %{http_code}\n' \
     -X DELETE http://api.pixomatix.com/api/users

Images API

Array of gallery objects : GET /api/galleries ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/galleries

Response

  [
    {
      "id":"3086ed853a7336bc",
      "caption":"All Pictures",
      "vertical":false,
      "is_photo":false,
      "is_gallery":true,
      "has_galleries":true,
      "has_photos":false,
      "has_parent":false,
      "thumbnail_url":"http://api.pixomatix.com/cache/ccdce535cf8cfdfd/f9882cb22f0453fc_200x200.jpg"
    },
    ...
  ]
  Response Code: 200

Gallery Object : GET /api/galleries/:id ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/galleries/3086ed853a7336bc

Response

  {
    "id":"3086ed853a7336bc",
    "caption":"All Pictures",
    "vertical":false,
    "is_photo":false,
    "is_gallery":true,
    "has_galleries":true,
    "has_photos":false,
    "has_parent":false,
    "thumbnail_url":"http://api.pixomatix.com/cache/ccdce535cf8cfdfd/f2e992a6cc8b8576_200x200.jpg"
  }
  Response Code: 200

Array of image objects in a gallery : GET /api/galleries/:id/photos ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/galleries/1d0946693f029960/photos

Response

  [
    {
      "id":"c256005c010b3996",
      "caption":null,
      "vertical":true,
      "is_photo":true,
      "is_gallery":false,
      "has_galleries":false,
      "has_photos":false,
      "has_parent":true,
      "parent_id":"1d0946693f029960",
      "thumbnail_url":"http://api.pixomatix.com/cache/1d0946693f029960/c256005c010b3996_200x200.jpg",
      "hdtv_url":"http://api.pixomatix.com/cache/1d0946693f029960/c256005c010b3996_1080.jpg",
      "original_url":"http://api.pixomatix.com/images/c256005c010b3996/original",
      "download_url":"http://api.pixomatix.com/images/c256005c010b3996/download"
    },
    ...
  ]
  Response Code: 200

Array of gallery objects in a gallery : GET /api/galleries/:id/galleries ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/galleries/3086ed853a7336bc/galleries

Response

  [
    {
      "id":"ccdce535cf8cfdfd",
      "caption":"Mc D, Hyderabad Central",
      "vertical":false,
      "is_photo":false,
      "is_gallery":true,
      "has_galleries":false,
      "has_photos":true,
      "has_parent":true,
      "parent_id":"3086ed853a7336bc",
      "thumbnail_url":"http://api.pixomatix.com/cache/ccdce535cf8cfdfd/4807869cde3ab130_200x200.jpg"
    },
    ...
  ]
  Response Code: 200

First photo id in a gallery if present : GET /api/galleries/:id/photo ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/galleries/ccdce535cf8cfdfd/photo

Response

  {
    "id":null
  }
  Response Code: 200

OR

  {
    "id":"5cf976e90781546b"
  }
  Response Code: 200

Parent id which has galleries (may be parent of parent and so on) : GET /api/galleries/:id/parent ↑ API

Request

curl -H 'Accept: application/vnd.pixomatix.v1' \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en-US' \
     -w '\nResponse Code: %{http_code}\n' \
     -X GET http://api.pixomatix.com/api/galleries/ccdce535cf8cfdfd/parent

Response

  {
    "parent_id":"3086ed853a7336bc"
  }
  Response Code: 200

Credits ↑

• Code for API constraints - RADD

About Me ↑

Kulbir Saini, Senior Developer / Programmer, Hyderabad, India

Contact Me

Kulbir Saini - contact [AT] saini.co.in / @_kulbir

License ↑

Copyright (c) 2015 Kulbir Saini

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.