PAPI.js (Pressly API)

Papi.js offers a Promise based abstraction for accessing the Pressly API.

Support

Papi.js will work on all modern browsers.

Internet Explorer

Papi.js uses CORS to make cross-origin requests. Only IE10+ have a proper implementation of CORS.

XDomain

Included is an XDomain distribution of Papi.js which will work on older browsers that do not properly support CORS (IE8 and IE9) located at dist/papi.xdomain.js.

NOTE Because IE8 is ECMASCRIPT version 3 You will need to include es5-shim and es5-sham as well https://github.com/es-shims/es5-shim

Download Release

Releases can be downloaded here https://github.com/pressly/papi.js/releases you can then script include /dist/papi.js in your project

<script type="text/javascript" src="papi.js"></script>

This will expose the Papi class globally.

API Docs

Login to https://beta.pressly.com
View docs at: https://beta-api.pressly.com/docs

Getting a JWT

Login to https://beta.pressly.com
Visit https://beta-api.pressly.com/auth/session and copy the jwt string

Connection

Papi::constructor(`options`)

options* (optional) | Object | see below

Most of the time you can simply create a new api instance from Papi without specifying any options:

var api = new Papi();

You can also optionally specify options.

Options

host | String | defaults to 'https://beta-api.pressly.com'
timeout | Integer | Global timeout in ms for all requests

var api = new Papi({ host: 'https://dev-api.pressly.com', timeout: 20000 });

Authentication

All authentication is handled under the Papi.auth module.

auth.login(`email`, `password`)

email (required) | String
password* (required) | String

Returns Promise which resolves session response.

api.auth.login(email, password).then(function(session) {
  // Returns logged in session
});

auth.logout()

Returns promise for successful logout.

api.auth.logout(email, password).then(function() {
  // User is successfully logged out
});

auth.get()

Returns promise which resolves the current session.

This will attempt to pass an authentication cookie if one exists to retreive the logged in session.

api.auth.get().then(function(session) {
  // Returns current session if already logged in
});

auth.set(`session`)

session (required) | Object | a stored session object.

You may wish to store the api.auth.session object on the client and restore it at a later time.

api.auth.set(session);

Resources

Before we can fetch data we need to set up the appropriate resource we wish to query.

$resource(`key`, `*params`)

key (required) | String | Key of the resource eg. 'hubs.assets'
params (optional) | Object | eg. { hubId: 123 }

Returns a prepared Resource.

Creating a resource

var resource = api.$resource('hubs'); // returns a Hubs Resource

Creating a nested resource

When directly specifying nested resources we use the format parent.child starting from the root.

var resource = api.$resource('hubs.assets'); // returns an Assets Resource

Preparing a resource with params

In cases where we are creating a nested resource we will need to specify the ids of the parents. This can be done at the time you request data from the resource via the all or find methods or you can prepare the resource with default params when you create it.

Note The param names for parent ids take the form {singular parent name }Id ie. hubs -> hubId

var resource = api.$resource('hubs.assets', { hubId: 123 }); // returns an Assets Resource with set hub id

Now this resource will be setup to return assets from hub '123'.

Here is an example of preparing a resource that is nested 3 deep. The styles resource.

var resource = api.$resource('hubs.apps.styles', { hubId: 123, appId: 456 }); // returns a Styles Resource with set hub and app id

Additional Modifiers

You can additionally set modifiers on the resource like limiting the number of results, or setting query params.

limit(`rpp`)

rpp (required) | Integer | Requests per page, Number or results to return for all and custom actions

Returns the resource.

resource.limit(15);

query(`params`)

params (required) | Object | Query params that will be set on the request ie. { q: 1, b: 2 } -> ?q=1&b=2

Returns the resource.

resource.query({ q: 1, b: 2 });

Because modifiers return the current resource you can chain them like so:

resource.limit(15).query({ q: 1, b: 2 });

timeout(`ms`)

Specify a maximum timeout before an error is triggered for requests on this resource

resource.timeout(20000);

Requests

Requesting data is done by the all and find methods on a Resource.

$all(`*params`)

params (optional) | Object | ex. { hubId: 123 } params will override anything set in the resource.

Returns a Promise which resolves an Array of result models.

resource.$all().then(function(hubs) {
  ...
});

$get(`params`)

params (optional) | Object | ex. { slug: 'some-article-slug' } params will override anything set in the resource.

returns a Promise which resolves a result model.

resource.$get({ slug: 'some-article-slug' }).then(function(hub) {
  ...
});

$find(`id` or `params`)

id (optional) | Integer | ex 123
params (optional) | Object | ex. { hubId: 123, id: 1 } params will override anything set in the resource.

returns a Promise which resolves a result model.

resource.$find(123).then(function(hub) {
  ...
});

Models can also `$resource` child resources to get associated data

Result models are extended with the resource that generated it so you can access $resource to generate child resources.

api.$resource('hubs').$find(123).then(function(hub) {
  hub.$resource('apps').$all().then(function(apps) {
    ..
  });
});

Notice that when you chain queries you specify the child name hubs rather than the full resource key hubs.apps.

This is equivalent to:

api.$resource('hubs').$find(123).then(function(hub) {
  api.$resource('hubs.apps', { hubId: hub.id }).$all().then(function(apps) {
    ..
  });
});

Working with Models and Collections

Models

Result models have methods to facilitate saving, deleting, updating, etc.

api.$resource('hubs').$find(123).then(function(hub) {
  hub.name = "My First Hub";

  hub.$save().then(() => {

  });
});

Collections

Collections are Arrays of Models which are extended with helper functions.

Collections are produced by the Resource::$all method.

var collection;
api.$resource('hubs').$all().then(function(hubs) {
  collection = hubs.findWhere({ name: "My First Hub"});
  ..
});

$find(`id`)

id (optional) | Integer | ex 123

returns a Model.

api.$resource('hubs').$all().then(function(hubs) {
  var model = hubs.findWhere({ name: "My First Hub"});
  ..
});

API Schema

Below outlines the schema of all the RESTful resources, their routes, associated model, and child resources.

###Account

accounts

#####Children

User accounts.users
Hub accounts.hubs

#####REST Endpoints

GET /accounts
POST /accounts
GET /accounts/:id
PUT /accounts/:id
DELETE /accounts/:id

Member Actions

POST /accounts/:id/become

###User

accounts.users

#####Parent

Account accounts

#####REST Endpoints

GET /accounts
POST /accounts
GET /accounts/:accountId/users/:id
PUT /accounts/:accountId/users/:id
DELETE /accounts/:accountId/users/:id

###Hub

accounts.hubs

#####Parent

Account accounts

See Hub hubs

#####REST Endpoints

GET /accounts
POST /accounts
GET /accounts/:accountId/hubs/:id
PUT /accounts/:accountId/hubs/:id
DELETE /accounts/:accountId/hubs/:id

###Hub

hubs

#####Children

App hubs.apps
Model hubs.analytics
Feed hubs.feeds
Invite hubs.invites
Recommendation hubs.recommendations
User hubs.users
Collection hubs.collections
Tag hubs.tags
Asset hubs.assets
Draft hubs.drafts

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:id
PUT /hubs/:id
DELETE /hubs/:id

Collection Actions

GET /hubs/search

Member Actions

POST /hubs/:id/upgrade
POST /hubs/:id/accept_invite
POST /hubs/:id/reject_invite

###App

hubs.apps

#####Parent

Hub hubs

#####Children

Style hubs.apps.styles

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/apps/:id
PUT /hubs/:hubId/apps/:id
DELETE /hubs/:hubId/apps/:id

Collection Actions

GET /hubs/current

Member Actions

GET /hubs/:hubId/apps/:id/build
GET /hubs/:hubId/apps/:id/status

###Style

hubs.apps.styles

#####Parent

App hubs.apps

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/apps/:appId/styles/:id
PUT /hubs/:hubId/apps/:appId/styles/:id
DELETE /hubs/:hubId/apps/:appId/styles/:id

###Model

hubs.analytics

#####Parent

Hub hubs

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/analytics/:id
PUT /hubs/:hubId/analytics/:id
DELETE /hubs/:hubId/analytics/:id

Collection Actions

GET /hubs/summary
GET /hubs/visitors
GET /hubs/pageviews
GET /hubs/duration

###Feed

hubs.feeds

#####Parent

Hub hubs

#####Children

FeedAsset hubs.feeds.assets

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/feeds/:id
PUT /hubs/:hubId/feeds/:id
DELETE /hubs/:hubId/feeds/:id

###FeedAsset

hubs.feeds.assets

#####Parent

Feed hubs.feeds

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/feeds/:feedId/assets/:id
PUT /hubs/:hubId/feeds/:feedId/assets/:id
DELETE /hubs/:hubId/feeds/:feedId/assets/:id

###Invite

hubs.invites

#####Parent

Hub hubs

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/invites/:id
PUT /hubs/:hubId/invites/:id
DELETE /hubs/:hubId/invites/:id

Collection Actions

POST /hubs/bulk_invite

Member Actions

POST /hubs/:hubId/invites/:id/resend
POST /hubs/:hubId/invites/:id/accept
POST /hubs/:hubId/invites/:id/reject

###Recommendation

hubs.recommendations

#####Parent

Hub hubs

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/recommendations/:id
PUT /hubs/:hubId/recommendations/:id
DELETE /hubs/:hubId/recommendations/:id

###User

hubs.users

#####Parent

Hub hubs

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/users/:id
PUT /hubs/:hubId/users/:id
DELETE /hubs/:hubId/users/:id

Collection Actions

POST /hubs/grant_access

Member Actions

DELETE /hubs/:hubId/users/:id/revoke_access

###Collection

hubs.collections

#####Parent

Hub hubs

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/collections/:id
PUT /hubs/:hubId/collections/:id
DELETE /hubs/:hubId/collections/:id

Collection Actions

PUT /hubs/reorder

###Tag

hubs.tags

#####Parent

Hub hubs

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/tags/:id
PUT /hubs/:hubId/tags/:id
DELETE /hubs/:hubId/tags/:id

###Asset

hubs.assets

#####Parent

Hub hubs

#####Children

Like hubs.assets.likes
Comment hubs.assets.comments

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/stream/:id
PUT /hubs/:hubId/stream/:id
DELETE /hubs/:hubId/stream/:id

Member Actions

PUT /hubs/:hubId/stream/:id/feature
PUT /hubs/:hubId/stream/:id/unfeature
PUT /hubs/:hubId/stream/:id/hide
PUT /hubs/:hubId/stream/:id/unhide
PUT /hubs/:hubId/stream/:id/lock
PUT /hubs/:hubId/stream/:id/unlock

###Like

hubs.assets.likes

#####Parent

Asset hubs.assets

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/stream/:assetId/likes/:id
PUT /hubs/:hubId/stream/:assetId/likes/:id
DELETE /hubs/:hubId/stream/:assetId/likes/:id

###Comment

hubs.assets.comments

#####Parent

Asset hubs.assets

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/stream/:assetId/comments/:id
PUT /hubs/:hubId/stream/:assetId/comments/:id
DELETE /hubs/:hubId/stream/:assetId/comments/:id

###Draft

hubs.drafts

#####Parent

Hub hubs

#####REST Endpoints

GET /hubs
POST /hubs
GET /hubs/:hubId/drafts/:id
PUT /hubs/:hubId/drafts/:id
DELETE /hubs/:hubId/drafts/:id

Member Actions

PUT /hubs/:hubId/drafts/:id/publish

###CodeRevision

code_revisions

#####Children

Hub code_revisions.hubs

#####REST Endpoints

GET /code_revisions
POST /code_revisions
GET /code_revisions/:id
PUT /code_revisions/:id
DELETE /code_revisions/:id

Member Actions

GET /code_revisions/:id/fetch_repo

###Hub

code_revisions.hubs

#####Parent

CodeRevision code_revisions

See Hub hubs

#####REST Endpoints

GET /code_revisions
POST /code_revisions
GET /code_revisions/:code_revisionId/hubs/:id
PUT /code_revisions/:code_revisionId/hubs/:id
DELETE /code_revisions/:code_revisionId/hubs/:id

###Model

signup

#####REST Endpoints

GET /signup
POST /signup
GET /signup/:id
PUT /signup/:id
DELETE /signup/:id

Member Actions

GET /signup/:id/account_uid_available
GET /signup/:id/account_email_available

###User

users

#####REST Endpoints

GET /users
POST /users
GET /users/:id
PUT /users/:id
DELETE /users/:id

Collection Actions

GET /users/roles

hubba / papi.js

PAPI.js (Pressly API)

Support

Internet Explorer

XDomain

Download Release

API Docs

Getting a JWT

Connection

Papi::constructor(`options`)

Options

Authentication

auth.login(`email`, `password`)

auth.logout()

auth.get()

auth.set(`session`)

Resources

$resource(`key`, `*params`)

Creating a resource

Creating a nested resource

Preparing a resource with params

Additional Modifiers

limit(`rpp`)

query(`params`)

timeout(`ms`)

Requests

$all(`*params`)

$get(`params`)

$find(`id` or `params`)

Models can also `$resource` child resources to get associated data

Working with Models and Collections

Models

Collections

$find(`id`)

API Schema

About

Languages

PAPI.js (Pressly API)

Support

Internet Explorer

XDomain

Download Release

API Docs

Getting a JWT

Connection

Papi::constructor(options)

Options

Authentication

auth.login(email, password)

auth.logout()

auth.get()

auth.set(session)

Resources

$resource(key, *params)

Creating a resource

Creating a nested resource

Preparing a resource with params

Additional Modifiers

limit(rpp)

query(params)

timeout(ms)

Requests

$all(*params)

$get(params)

$find(id or params)

Models can also $resource child resources to get associated data

Working with Models and Collections

Models

Collections

$find(id)

API Schema

About

Languages

Papi::constructor(`options`)

auth.login(`email`, `password`)

auth.set(`session`)

$resource(`key`, `*params`)

limit(`rpp`)

query(`params`)

timeout(`ms`)

$all(`*params`)

$get(`params`)

$find(`id` or `params`)

Models can also `$resource` child resources to get associated data

$find(`id`)