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.


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.


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


  local req = parse.request( )

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

A request returns meta for the currently logged in user.

Additional parameters may be required depending on the endpoint.


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

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



Every parse.request() must have a response listener attached to it before it will fire. For example, in the previous code, the request is set up, but won't do anything until it has a :response() method added.

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

  local req = parse.request( )

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.


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

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 docs, the curl -d flag shown in the examples indicates the usage of :data() or :set() in the Corona plugin request.


Setting :data() at anytime will clear any previous data for the request, including data added with the :set() method. There can on be only one data object per request.

:set( name, value )

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


The name key must be a string.

:where( query_tbl_or_json )

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


Anytime you see the usage of {where=...} in the docs, it's an indicator that the method will probably use :where() in the Corona plugin request.

: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.


When you see the usage of the --data-urlencode curl flag in the docs, then this indicates something that should be put in the :options() method. The method can accept a Lua table or a raw JSON string.

: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 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:


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


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

  parse.request( ):response(cb)


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


  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)
      if info.status == 200 then
        print( res.color, res.age )