Making REST service calls from OpenAF

OpenAF includes several ways to make HTTP connections and retrieve data from them. An usually the most usefull connections are to services that expose some kind of REST API “talking” in JSON. To make it easy in OpenAF to make these calls and parse the corresponding output the shortcut $rest was created.

Simple examples

GET

Performing a simple REST GET operation:

> $rest().get("https://ifconfig.co/json");
{
  "ip": "1.2.3.4",
  "country": "Ireland",
  "country_eu": true,
  "country_iso": "IE",
  "city": "Dublin",
  "hostname": "ec2-1-2-3-4.eu-west-1.compute.amazonaws.com",
  "latitude": 53.3338,
  "longitude": -6.2488,
  "asn": "AS16509",
  "asn_org": "Amazon.com, Inc."
}

The return is a parsed json object ready to use.

POST

Performing a REST POST operation you can pass the JSON body directly (in this example the httpbin.org service will echo the post request made):

> $rest().post("https://httpbin.org/post", { a: 1, b: "xyz", c: true }).json
{
  "a": 1,
  "b": "xyz",
  "c": true
}

PUT

The same goes for the PUT verb.

> $rest().put("https://httpbin.org/put", { a: 1, b: "xyz", c: true }).json
{
  "a": 1,
  "b": "xyz",
  "c": true
}

PATCH

And the PATCH verb.

> $rest().patch("https://httpbin.org/patch", { a: 1, b: "xyz", c: true }).json
{
  "a": 1,
  "b": "xyz",
  "c": true
}

DELETE

Finally, the DELETE verb.

> $rest().delete("https://httpbin.org/delete").json
null

Passing resource/query elements

There are two ways:

1. Using the URI path (resource)

// https://some.server/restAPI/category/abc/article/1234
$rest().get("https://some.server/restAPI", { category: "abc", article: 1234 });

$rest().post("https://some.server/restAPI", { 
    article: 1234, title: "My article" 
}, { category: "abc", article: 1234 });

$rest().put("https://some.server/restAPI", { 
    article: 1234, title: "My article updated" 
}, { category: "abc", article: 1234 });

$rest().delete("https://some.server/restAPI", { category: "abc", article: 1234 });

1. Using the query string

// https://some.server/restAPI?category=abc&article=1234
$rest({ uriQuery: true }).get("https://some.server/restAPI", { category: "abc", article: 1234 });

$rest({ uriQuery: true }).post("https://some.server/restAPI", { 
    article: 1234, title: "My article" 
}, { category: "abc", article: 1234 });

$rest({ uriQuery: true }).put("https://some.server/restAPI", { 
    article: 1234, title: "My article updated" 
}, { category: "abc", article: 1234 });

$rest({ uriQuery: true }).delete("https://some.server/restAPI", { category: "abc", article: 1234 });

What if the body is URL encoded?

When you need the request body to be “application/x-www-form-urlencoded” and instead of “application/json” you can use the option urlEncode=true.

> $rest({ urlEncode: true }).post("https://httpbin.org/post", { a: 1, b: "xyz" }).form
{
  "a": "1",
  "b": "xyz"
}

This was a simple introduction to the $rest shortcut. Check all the available options (e.g. authentication, timeout, exception control, etc...) executing “help $rest.get” from an openaf-console.