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.
Heads Up!
Coronium only uses the GET
and POST
HTTP methods.
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:
Run The Code
This example code is included on a fresh install of Coronium. You can run it with https://your.coronium.instance/echo/test?hello=me
.
--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"}
JSON Conversion
When using the Corona SDK module, any incoming JSON
is converted to a Lua
table on the client. See Client Usage for more details.
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
Heads Up!
cloud.JSON
is the default outgoing type and does not need to be specified.
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.
Did You Know?
Plain text results are used often for IoT commuications.
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.