Rack::Passbook

This is still in early stages of development, so proceed with caution when using this in a production application. Any bug reports, feature requests, or general feedback at this point would be greatly appreciated.

Passbook is an iOS 6 feature that manages boarding passes, movie tickets, retail coupons, & loyalty cards. Using the PassKit API, developers can register web services to automatically update content on the pass, such as gate changes on a boarding pass, or adding credit to a loyalty card.

Apple provides a specification for a REST-style web service protocol to communicate with Passbook, with endpoints to get the latest version of a pass, register / unregister devices to receive push notifications for a pass, and query for passes registered for a device.

This project is an example implementation of this web service specification in Rails, and will serve the basis for a more comprehensive Rails generator in the near future.

If you're just starting out Passbook development, you should definitely check out this great two-part tutorial by Marin Todorov (Part 1 Part 2).

Installation

$ gem install rack-passbook

Requirements

• Ruby 1.9
• PostgreSQL 9.1 running locally (Postgres.app is the easiest way to get a Postgres server running on your Mac)

Example Usage

Rack::Passbook can be run as Rack middleware or as a single web application. All that is required is a connection to a Postgres database.

config.ru

require 'bundler'
Bundler.require

run Rack::Passbook

An example application can be found in the /example directory of this repository.

---

Specification

What follows is a summary of the specification. The complete specification can be found in the Passbook Web Service Reference.

Getting the Latest Version of a Pass

GET http://example.com/v1/passes/:passTypeIdentifier/:serialNumber

• passTypeIdentifier The pass’s type, as specified in the pass.
• serialNumber The unique pass identifier, as specified in the pass.

Response

• If request is authorized, return HTTP status 200 with a payload of the pass data.
• If the request is not authorized, return HTTP status 401.
• Otherwise, return the appropriate standard HTTP status.

Getting the Serial Numbers for Passes Associated with a Device

GET http://example.com/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier[?passesUpdatedSince=tag]

• deviceLibraryIdentifier A unique identifier that is used to identify and authenticate the device.
• passTypeIdentifier The pass’s type, as specified in the pass.
• serialNumber The unique pass identifier, as specified in the pass.
• passesUpdatedSince Optional A tag from a previous request.

Response

If the passesUpdatedSince parameter is present, return only the passes that have been updated since the time indicated by tag. Otherwise, return all passes.

• If there are matching passes, return HTTP status 200 with a JSON dictionary with the following keys and values:
  • lastUpdated (string) The current modification tag.
  • serialNumbers (array of strings) The serial numbers of the matching passes.
• If there are no matching passes, return HTTP status 204.
• Otherwise, return the appropriate standard HTTP status.

Registering a Device to Receive Push Notifications for a Pass

POST http://example.com/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber

• deviceLibraryIdentifier A unique identifier that is used to identify and authenticate the device.
• passTypeIdentifier The pass’s type, as specified in the pass.
• serialNumber The unique pass identifier, as specified in the pass.

The POST payload is a JSON dictionary, containing a single key and value:

• pushToken The push token that the server can use to send push notifications to this device.

Response

• If the serial number is already registered for this device, return HTTP status 200.
• If registration succeeds, return HTTP status 201.
• If the request is not authorized, return HTTP status 401.
• Otherwise, return the appropriate standard HTTP status.

Unregistering a Device

DELETE http://example.com/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber

• deviceLibraryIdentifier A unique identifier that is used to identify and authenticate the device.
• passTypeIdentifier The pass’s type, as specified in the pass.
• serialNumber The unique pass identifier, as specified in the pass.

Response

• If disassociation succeeds, return HTTP status 200.
• If the request is not authorized, return HTTP status 401.
• Otherwise, return the appropriate standard HTTP status.

---

Contact

Mattt Thompson

• http://github.com/mattt
• http://twitter.com/mattt
• m@mattt.me

License

Rack::Passbook is available under the MIT license. See the LICENSE file for more info.