Cloud : API Object

See Also: API Construction

The cloud.api object holds all of the "api" calls to your project. It's a routing mechanism that can return different types of output depending upon the needs of the developer (see below).

The api is "REST-like", but removes the cruft for Coronium usage.

Building an API

All "api" calls are placed in the api.lua file in your specific app folder. While you can require other Lua modules into the api.lua file, all input and output must travel through the api.lua, and in turn, the api object.

What follows is an example api.lua file:

--apps/echo/api.lua
local api = cloud.api()

function api.get.test(input)
  return input
end

return api

Request Paths

The way you structure your api determines how the request paths are structured. To normalize your api path, you combine like so:

/project_name/api_function

You'll generally use the http POST method most, via the Corona SDK module. But when creating Pages you will use GET which allows you to pass arguments to your method:

/project_name/api_function?arg=val&arg2=val2

The arguments are converted to a Lua table upon entry to the api.lua:

--apps/site/api.lua
local api = cloud.api()

function api.get.home(input)
  local arg1 = input.arg
  local arg2 = input.arg2

  return "arg1 is" .. arg1
end

return api

The request path for the above home method, would be:

https://your.coronium.instance/site/home?arg=val&arg2=val2

Since JSON is the default return type, the following would be displayed:

{"result":"arg1 is val"}

Output Types

The three types of data output suported by the api are JSON, HTML, and plain TEXT. These types are represented by the following constants:

cloud.JSON

cloud.HTML

cloud.TEXT

Note: See the template module for detailed information on using the cloud.HTML output type.

Using Output Types

Most often you'll be using the default cloud.JSON output, which does not need to be specified. If you're outputting plain text or rendered HTML, then you must include the output constant like so:

cloud.HTML

local api = cloud.api()

function api.get.info()
  local some_html = "<h1>Hello Lua!</h1>"
  return some_html, cloud.HTML --content-type=text/html
end

return api

The code above will display a web page with the heading "Hello Lua!" to the user.

cloud.TEXT

local api = cloud.api()

function api.get.note()
  local note = "Just some plain old-fashioned text here."
  return note, cloud.TEXT --content-type=text/plain
end

return api

The code above will return a plain text result, void of any browser decorations.

cloud.JSON

This is the default return type, and as such, is not required to be specified. Coronium will try to convert whatever you return to JSON. All data is piped to the client in a result key. The result may be a single value (string, number, or boolean), a table object, or table array, depending on the return value.