Examples

Some examples of how to use the published webservices by amforeas using different tools. This are based on a table named user on a database called amforeas created with the following command (HSQL):

 CREATE TABLE user (
   id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 0 INCREMENT BY 1) PRIMARY KEY, 
   name VARCHAR(25), 
   age INTEGER, 
   birthday DATE, 
   lastupdate TIMESTAMP, 
   credit DECIMAL(6,2))

Create a user

curl -X POST -d '{"name":"foo user", "age":30, "credit":45.0, "birthday":"1979-11-01"}' "http://localhost:8080/amforeas/demo1/user"

Query the user table

There are three different ways to obtain a registry from the user table.

By resource primary key (id)

curl "http://localhost:8080/amforeas/demo1/user/0"

If the primary key for the resource is not id, add the Primary-Key header:

curl -H "Primary-Key: users_id" "http://localhost:8080/amforeas/demo1/user/0"

By resource value

curl "http://localhost:8080/amforeas/demo1/user/id/0"
curl "http://localhost:8080/amforeas/demo1/user/name/foo%20bar"
curl "http://localhost:8080/amforeas/demo1/user/age/30"

This queries will return all the results that match (name = 'foo bar' or age = 30) ordered by the primary key. If the primary key for the resource is not id, add the Primary-Key header.

By Grails style dynamic finders

I love Dynamic Finders in Grails, that's why you can use them with amforeas:

curl "http://localhost:8080/amforeas/demo1/user/dynamic/findByAgeLessThanEquals?value=30"
curl "http://localhost:8080/amforeas/demo1/user/dynamic/findAllByNameLike?value=%25foo%25"
curl "http://localhost:8080/amforeas/demo1/user/dynamic/findByCreditIsNull"
curl "http://localhost:8080/amforeas/demo1/user/dynamic/findAllByCreditIsNotNull"
curl "http://localhost:8080/amforeas/demo1/user/dynamic/findAllByAgeOrAge?values=30&values=20"
curl "http://localhost:8080/amforeas/demo1/user/dynamic/findAllByAgeBetween?values=18&values=100"

Modifiers

Amforeas requests can accept modifiers to filter, sort or limit data.

Limit & Paging

By using LIMIT and OFFSET parameters, you can limit the number of records to retrieve:

GET amforeas/demo1/user/age/30?limit=25&offset=25

Will return records from rows 25 to 50.

You can also use the convenient PAGE parameter:

GET amforeas/demo1/user/age/30?page=2

By default, the page size is of 25. This value can be configured with the amforeas.server.page.size key or can be set on each request:

GET amforeas/demo1/user/age/30?page=2&pageSize=100

Again, by default, pageSize has a maximum value of 500 which can also be configured with the amforeas.server.page.size.max key.

Ordering

Basically translate to SQL ORDER BY queries. For example:

GET amforeas/demo1/user/age/30?sort=age&dir=asc

As with SQL, only asc and desc are possible.

Columns

Also, read requests can be limited to a certain number of columns using the COLUMNS parameter. By default, Amforeas will retrieve all columns (SELECT *) but this can be limited. For example:

GET amforeas/demo1/user/age/30?columns=name,age,birthday

Putting it all together:

GET amforeas/demo1/user/age/30?columns=name,age,birthday&page=1&pageSize=30&sort=name&dir=desc

If you want more complex queries, try with stored procedures or functions.

Stored Procedures & Functions

You can call stored procedures or functions with the /database/call/myFunction URI:

curl -X POST -d '[]' -H "Accept: application/json" /
-H "Content-Type: application/json" /
"http://localhost:8080/amforeas/demo1/call/myFunction"

Here we are calling a function which doesn't need any parameters. If the function defines the usage of parameters you can pass them following the JSON format:

curl -X POST \
  -d '[{"value":2010, "name":"year", "outParameter":false, "type":"INTEGER", "index":1},]' \
  -H "Accept: application/json" /
  -H "Content-Type: application/json" /
  "http://localhost:8080/amforeas/demo1/call/myFunctionWithParams"

This format is really simple and needs of five fields:

• name
• value
• type (INTEGER, VARCHAR, etc)
• outParameter
• index (position of the parameter as defined in the function/procedure)

For example:

 [
   {"value":2010, "name":"year", "outParameter":false, "type":"INTEGER", "index":1},
   {"name":"out_total", "outParameter":true, "type":"INTEGER", "index":2}
 ]