The Parse plugin follows a simple pattern for making requests to the Parse REST API. The plugin facilitates the entire REST API. By reading through the Parse REST API Guide you will have a much easier time working with this plugin.

Request¶

It all starts with a request to Parse, and completes with a response from Parse. What happens in-between that depends on the API call being used. All responses are returned in a Lua table.

parse.request¶

A parse.request requires one of the Parse REST API "endpoint objects" as the first parameter.

Example:

  local req = parse.request( parse.User.me )

This will make a request to the Parse.com User endpoint, asking for the me resource.

A parse.User.me request returns meta for the currently logged in user.

Additional parameters may be required depending on the endpoint.

Example:

  local req = parse.request( parse.Object.update, "Pets", "1234abcd" )

A parse.Object.update request requires a class and objectId parameter.

Response¶

What follows is the bare minimum needed for a working request:

  local req = parse.request( parse.User.me )
  req:response()

To capture any incoming data, we need to provide a callback function to the response listener. The callback function receives three parameters; the success state (ok), the data, if any, as a table (res), and an (info) table that contains various information about the request and response that took place.

Example:

  local req = parse.request( parse.User.me )
  req:response(function( ok, res, info )
    if not ok then
      print( 'err', res )
    else
      print( res.username )
      print( info.status )
    end
  end)

Request Methods¶

The request methods are used in-between the request and response -- similar to middleware -- to perform certain functions depending upon the endpoint being used. The request methods are as follows, some are mutually exclusive for the request.

:data( tbl_or_json )

The data object to send to Parse. Can be a Lua table or raw JSON string. When viewing the Parse.com docs, the curl -d flag shown in the examples indicates the usage of :data() or :set() in the Corona plugin request.

:set( name, value )

Helper. Sets a value on the data object. If the data object is a JSON string, no action is performed.

:where( query_tbl_or_json )

When using "query" based endpoints, you provide the query parameters using the :where() method.

:options( { name1 = value1, name2 = value2 } )

The :options() method is used to add values to the request query string. This can be used to add special Parse keys like count, order, limit, etc. The :options() method can be added to most requests that return bulk data sets.

:header( name, value )

Helper. Adds a custom header to the request to be sent to Parse. Can be used multiple times.

In most cases you won't need to use this method, as the standard headers are already sent in the background. There are a few use cases for additional headers in the Parse.com docs. Use this method to add any.

:progress( ok, bytesTrans, bytesEst )

Used as a progress status listener for upload and download file events. See Using Files. The listener receives a status (ok), the bytes transferred (bytesTrans), and the estimated bytes to go (bytesEst). Use to follow file transfer progress.

Coding Styles¶

You can use a variable, chain, or stack the various request methods, whatever fits your coding style best:

Variable

  local req = parse.request( parse.Config.get )
  req:response(function( ok, res )
    if not ok then
      print('err', res)
    else
      print(res.color, res.age)
    end
  end)

Chaining

  --Setup callback
  local function cb( ok, res, info )
    print( ok, res, info )
  end

  parse.request( parse.User.me ):response(cb)

  --OR

  parse.request( parse.User.get, "1234abcd" ):options({keys='username'}):response(cb)

Stacking

  parse.request( parse.Objects.query, "Pets" )
  :where( { color = "Green", age = { ["$gt"] = 20 } )
  :options( { limit = 20, order = "age" } )
  :header("X-Secret-Msg", "some-value")
  :response(function( ok, res, info )
    if not ok then
      print('err', res)
    else
      if info.status == 200 then
        print( res.color, res.age )
      end
    end
  end)