Chapter 2

To get started with a new app, you'll need to gather both your Application ID and your REST API Key from your Parse.com dashboard settings area.

Using the Config¶

The plugin Config module allows you to store commonly needed values for making Parse requests. If the config values are set, they will automatically be used when needed.

At the bare minimum we must add the Parse app Application ID and REST API Key to the plugin Config (Not to be confused with parse.Config).

On the main page, or near the start of your app, you should set your Config values:

local parse = require 'plugin.parse'

--== These settings are mandatory for the plugin
parse.config:applicationId("your-application-id")
parse.config:restApiKey("your-rest-api-key")
--== Optional setting for external Parse-Server
parse.config:cloudAddress("https://my.parse.server:port/api_prefix")

Now the auth data is stored and can be used for requests.

Plugin Config Methods

The plugin config methods are both getters and setters. The only parameter options are true or false. You can also remove the method from the code altogether, essentially setting the config option to false.

-- Set debug enabled
parse.config:debugEnabled( true )
-- Get debug enables value
local debug_on = parse.config:debugEnabled()

Config Options

Option	Details	Required
:cloudAddress	External Parse-Server endpoint	Depends on hosting
:applicationId	The Parse app id	Yes
:restApiKey	The Parse app REST api key	Yes
:debugEnable	Print incoming data to the terminal	No
:debugVerbose	Print all incoming data	No
:installationId	An install id	Depends on method
:timeout	Time to wait for a response	No - default: 30

Debug Mode¶

The plugin config also handles enabling the debugging output, which can be very helpful while building out your app, as the data is output to the terminal automatically. You can turn on the debug flag to get a print out of data in your Config:

  parse.config:debugEnabled()

This mode will print out the response data, but nothing more. If you'd like to see all the response, and some request data, add verbose debugging:

  parse.config:debugEnabled()
  parse.config:debugVerbose(true)

If you need to disable debugging temporarily, you can pass false to either debug method, or just remove them.

Add Config Extras¶

You can add other values to the config that you can use throughout your app.

-- Set custom config value
parse.config:set("app_title", "MyApp")

-- Get custom config value
local appTitle = parse.config:get("app_title")

Parsing It Out¶

You'll spend most of your time learning how to use the plugin, and Parse, by reading the Parse REST API guide. It offers examples, useful notes, and advice for every piece of functionality in the API.

The Parse Plugin can handle every situation, but you will need to learn a bit about "translating" the curl examples on Parse.com, because sadly, it's not displayed in Lua.

Some Tips for The Road Ahead¶

Here are some things to look out for in the Parse.com curl examples:

A -d flag is short for 'data', this pairs with the :data() or :set() methods.
A -data-urlencode flag pairs with the :options() method.
A where={...} will usually pair with the :where() method.
Ignore any -H flags (header). These are handled by the plugin.
Ignore the url path, you'll use the request object constants.

Be sure to read the Parse to Lua chapter.

Examples¶

Logging in a User

  curl -X GET \
    -H "X-Parse-Application-Id: 9Ad8ugrxMiwTpgzH7IG7fjKsE07Xevroofy3fS1K" \
    -H "X-Parse-REST-API-Key: bgc8cqUdipxZDyPINvilTg5vacyivf8bJ1VQcH2I" \
    -H "X-Parse-Revocable-Session: 1" \
    -G \
    --data-urlencode 'username=cooldude6' \
    --data-urlencode 'password=p_n7!-e8' \
    https://api.parse.com/1/login

In this login example from Parse.com, we can see the structure of a "GET" method. You should notice the two --data--urlencode values. This gives us a clue that we should us the :options() method. Since this is the login method, we need to use the correct endpoint object. In this case that would be parse.User.login. Let's see what it would look like in the client code:

  --Lua
  parse.request( parse.User.login )
  :options( { username = "cooldude6", password = "p_n7!-e8" } )
  :response(cb)

Check Session / Current User

A User must be logged in for the following to work.

  curl -X GET \
    -H "X-Parse-Application-Id: 9Ad8ugrxMiwTpgzH7IG7fjKsE07Xevroofy3fS1K" \
    -H "X-Parse-REST-API-Key: bgc8cqUdipxZDyPINvilTg5vacyivf8bJ1VQcH2I" \
    -H "X-Parse-Session-Token: r:pnktnjyb996sj4p156gjtp4im" \
    https://api.parse.com/1/users/me

This one is super simple. There isn't anything we need to convert, except the endpoint, which in this case would be parse.User.me. We also check for a 209 code from Parse, which is 'invalid session token'.

  --Lua
  parse.request( parse.User.me )
  :response(function( ok, res, info )
    if res.code == 209 then
      --session is gone
      --need a relogin
    end
  end)

Get an Object by ID

  curl -X GET \
    -H "X-Parse-Application-Id: 9Ad8ugrxMiwTpgzH7IG7fjKsE07Xevroofy3fS1K" \
    -H "X-Parse-REST-API-Key: bgc8cqUdipxZDyPINvilTg5vacyivf8bJ1VQcH2I" \
    https://api.parse.com/1/classes/GameScore/Ed1nuqPvcm

Another simple one:

  parse.request( parse.Object.get, "GameScore", "Ed1nuqPvcm" )
  :response(cb)

Create an Object with raw JSON

  curl -X POST \
    -H "X-Parse-Application-Id: aOeTz9iwexrJOh7a9mE9ZzE2swBpQP3fwgp82cdV" \
    -H "X-Parse-REST-API-Key: ZbtvAjlxJ5obTDTwkG44FWYeepdaXJvNnxAFIDKr" \
    -H "Content-Type: application/json" \
    -d '{"playerName":"develephant","cheatMode":false}' \
    https://api.parse.com/1/classes/GameScore

Generally you would use Lua tables in the plugin, but in certain cases it may be easier just to use the straight JSON.

  parse.request( parse.Object.create, "GameScore" )
  :data([[{"playerName":"develephant","cheatMode":false}]])
  :response(cb)

Warning

For literal strings in Lua, you must enclose the content with double brackets on each end of the text [[some string content]]. Remember that spaces will be preserved so you need to make sure you keep the brackets in tight around the content.

Query an Object with raw JSON

  curl -X GET \
    -H "X-Parse-Application-Id: 9Ad8ugrxMiwTpgzH7IG7fjKsE07Xevroofy3fS1K" \
    -H "X-Parse-REST-API-Key: bgc8cqUdipxZDyPINvilTg5vacyivf8bJ1VQcH2I" \
    -G \
    --data-urlencode 'where={"playerName":"develephant","cheatMode":false}' \
    https://api.parse.com/1/classes/GameScore

Even though it's --data--urlencode, the where= takes precedence, so you would use a :where() method. Now, the key to using raw JSON in a :where() method is making sure there are no spaces between the double brackets, or the call will fail.

  parse:request( parse.Object.query, "GameScore" )
  :where([[{"playerName":"develephant","cheatMode":false}]])
  :response(cb)

Tip

In most cases you should use Lua tables for data, it's better for conversion and error handling. Plus you have a table.

Creating an Installation

  curl -X POST \
    -H "X-Parse-Application-Id: 9Ad8ugrxMiwTpgzH7IG7fjKsE07Xevroofy3fS1K" \
    -H "X-Parse-REST-API-Key: bgc8cqUdipxZDyPINvilTg5vacyivf8bJ1VQcH2I" \
    -H "Content-Type: application/json" \
    -d '{
          "deviceType": "ios",
          "deviceToken": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "channels": [
            ""
          ]
        }' \
    https://api.parse.com/1/installations

This is a little more of a challenge and may work best with raw JSON, but we'll convert to tables instead:

  parse.request( parse.Installation.create )
  :data({
    deviceType = "ios",
    deviceToken = "0123456789abcdef0123456789ab",
    channels = {
      ""
    }
  })
  :response(cb)

Sign up and login with Twitter

  curl -X POST \
    -H "X-Parse-Application-Id: 9Ad8ugrxMiwTpgzH7IG7fjKsE07Xevroofy3fS1K" \
    -H "X-Parse-REST-API-Key: bgc8cqUdipxZDyPINvilTg5vacyivf8bJ1VQcH2I" \
    -H "X-Parse-Revocable-Session: 1" \
    -H "Content-Type: application/json" \
    -d '{
          "authData": {
            "twitter": {
              "id": "12345678",
              "screen_name": "ParseIt",
              "consumer_key": "SaMpLeId3X7eLjjLgWEw",
              "consumer_secret": "SaMpLew55QbMR0vTdtOACfPXa5UdO2THX1JrxZ9s3c",
              "auth_token": "12345678-SaMpLeTuo3m2avZxh5cjJmIrAfx4ZYyamdofM7IjU",
              "auth_token_secret": "SaMpLeEb13SpRzQ4DAIzutEkCE2LBIm2ZQDsP3WUU"
            }
          }
        }' \
    https://api.parse.com/1/users

In Lua...

  local data_tbl =
  {
    authData = {
      twitter = {
        id = "12345678",
        screen_name = "ParseIt",
        consumer_key = "SaMpLeId3X7eLjjLgWEw",
        consumer_secret = "SaMpLew55QbMR0vTdtOACfPXa5UdO2THX1JrxZ9s3c",
        auth_token = "12345678-SaMpLeTuo3m2avZxh5cjJmIrAfx4ZYyamdofM7IjU",
        auth_token_secret = "SaMpLeEb13SpRzQ4DAIzutEkCE2LBIm2ZQDsP3WUU"
      }
    }
  }

  parse.request( parse.User.create )
  :data( data_tbl )
  :response(cb)