Introduction to rest.li

Rest.li
Development Workflow Overview
Joe Betz, April 2014

Let’s implement a Simple REST request

GET /fortunes/1 HTTP/1.1
Accept: application/json
Request

GET /fortunes/1 HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: …
!
{
"message": "Today’s your lucky day!"
}
Request Response

Step 1. Write a Data Schema
Fortune.pdsc
{
"name" : "Fortune",
"namespace" : "com.example",
"type" : "record",
"fields" : [
{ "name" : "message", "type" : "string" }
]
}

Fortune.pdsc
{
"name" : "Fortune",
"type" : "record",
"fields" : [
]
}
This schema defines a Fortune record. It has
a single message field of type string. Rest.li
schemas are based on avro schemas, and
supports maps, lists, optional fields, unions and
other useful data modeling constructs.

Fortune.pdsc
{
"name" : "Fortune",
"type" : "record",
"fields" : [
]
}
Rest.li schemas are designed for JSON. Here’s
what a Fortune looks like in JSON:
{
“message”: “Today is your lucky day!”
}

Fortune.pdsc
{
"name" : "Fortune",
"type" : "record",
"fields" : [
]
}
Rest.li’s automatically generates a binding class from our data schema:

Fortune.pdsc
{
"name" : "Fortune",
"type" : "record",
"fields" : [
]
}
Fortune.java
public class Fortune extends
RecordTemplate {
String getMessage();
void setMessage(String);
}
Generated
Code

Fortune.pdsc
{
"name" : "Fortune",
"type" : "record",
"fields" : [
]
}
Fortune.java
public class Fortune extends
RecordTemplate {
String getMessage();
void setMessage(String);
}
Generated
Code
This class is important, we’ll use it in a minute.

FortunesResource.java
@RestLiCollection(name = "fortunes")
class FortunesResource implements KeyValueResource<Long, Fortune> {
!
@RestMethod.GET
public Fortune get(Long key) {
return new Fortune()
.setMessage("Today’s your lucky day!");
}
}
Step 2. Write a REST Resource

!
@RestMethod.GET
}
}
Rest.li annotation declares this class as our
implementation of the /fortunes resource.

!
@RestMethod.GET
}
}
Our collection contains
Fortune entities, keyed by
Long.

!
@RestMethod.GET
}
}
Our collection contains
Fortune entities, keyed by
Long.
Notice how we use the
generated Fortune class
here so everything is strongly
typed.

!
@RestMethod.GET
}
}
Here we implement HTTP GET

!
@RestMethod.GET
}
}
From our resource implementation,
Rest.li’s automatically generates an interface definition,

!
@RestMethod.GET
}
}
fortunes.restspec.json
{
“path”: “/fortunes”,
“supports”: [ “get” ],
…
}
Rest.li’s automatically generates an interface definition,
Generated
Code

!
@RestMethod.GET
}
}
{
…
}
Rest.li’s automatically generates an interface definition, and client bindings.
Generated
Code

!
@RestMethod.GET
}
}
FortunesBuilders.java
public class FortunesBuilders {
GetRequestBuilder get();
}
{
…
}
Generated
Code Generated
Code

!
@RestMethod.GET
}
}
FortunesBuilders.java
public class FortunesBuilders {
GetRequestBuilder get();
}
{
…
}
Generated
Code Generated
Code
We’ll use these to build our client.

Step 3. Write a Client
ExampleClient.java
Response response = restClient.sendRequest(new FortunesBuilders.get().id(1L)).get();
Fortune fortune = response.getEntity();
System.out.println(fortune.getMessage());

ExampleClient.java
We use client bindings generated
from our /fortune resource to build
an HTTP GET Request.

ExampleClient.java
And we use the Rest.li RestClient to
send the request.

ExampleClient.java
send the request.
Notice how everything is strongly typed.

ExampleClient.java
send the request.
Notice how everything is strongly typed.
But wait, this request is blocking! The .get() forces the
thread block and wait for a response from the server. We’ll
show how to make this non-blocking shortly.

Step 4. Run it!
“Today’s your lucky day!”

Step 4. Run it!
Great! but all our code is synchronous and blocking. What about non-blocking?

Importance of async, non-blocking request
handling

handling
Async processing is ideal for making multiple requests to backend systems in parallel and then
composing the results of those parallel requests into a single response. For modern internet
architectures, where many backend systems are involved in handling each request from a consumer,
making calls in parallel to these backend systems dramatically reduces the overall time to response
back to the consumer.

handling
Async processing is ideal for making multiple requests to backend systems in parallel and then
composing the results of those parallel requests into a single response. For modern internet
architectures, where many backend systems are involved in handling each request from a consumer,
making calls in parallel to these backend systems dramatically reduces the overall time to response
back to the consumer.
Servers running async code scale better because they can handle very large numbers of
concurrent requests. This is because, when you write async code, no threads are blocked waiting
for something to complete. If you don’t write async code and you need to handle large numbers of
concurrent requests, you’ll need one thread per concurrent request. Each thread takes up
considerable memory, and when you run out of memory (or max out a thread pool), the server is
unable to take on more requests, resulting in timed out requests and in cases of many complex
architectures, cascading failure.

Async in Rest.li
Rest.li integrates with ParSeq for both client and server side
async.

Async in Rest.li
async.
Using ParSeq, we will write Tasks. Tasks can be composed
together in parallel (par) or sequence (seq) into larger tasks.
Tasks are executed asynchronously by the ParSeq engine.

Async in Rest.li
async.
Using ParSeq, we will write Tasks. Tasks can be composed
together in parallel (par) or sequence (seq) into larger tasks.
Tasks are executed asynchronously by the ParSeq engine.
Let’s modify our Resource Implementation and Client to use
ParSeq.

Async Resource Implementation
class FortunesResource
implements KeyValueResource<Integer, Fortune> {
!
@RestMethod.GET
public Task<Fortune> get(Long key) {
Task<String> retrieveFortuneStr = … ;
!
Task<Fortune> buildFortune =
Tasks.action("getFortune", new Callable<Fortune>() {
@Override public Fortune call() throws Exception {
.setMessage(retieveFortuneStr.get());
}
});
return Tasks.seq(retrieveFortuneStr, buildFortune);
}
}

!
@RestMethod.GET
!
}
});
}
}
Rest.li resources methods can
return a ParSeq Task. Rest.li will
execute them asynchronously
and respond with the result when
it’s available.

!
@RestMethod.GET
!
}
});
}
}
Here we compose together
two tasks together in
sequence using Tasks.seq

!
@RestMethod.GET
!
}
});
}
}
The retrieveFortuneStr task is
a non-blocking IO task to get a
fortune string.

!
@RestMethod.GET
!
}
});
}
}
The retrieveFortuneStr task is
a non-blocking IO task to get a
fortune string.
The buildFortune task will
create a Fortune from the result
of the retrieveFortuneStr task.
Notice how .get() is used to
access the value of the
completed retrieveFortuneStr.

Async Client
FortuneClient.java
Task<Response<Fortune>> getFortune =
parSeqClient.createTask(new FortunesBuilders.get().id(1L));
!
final Task<Void> printFortune =
Tasks.action("printFortune", new Runnable() {
@Override public void run() {
Response<Fortune> response = getFortune.get();
Fortune fortune = getResponseEntity();
}
});
!
engine.run(Tasks.seq(getFortune, printFortune));
!
printFortune.await();

Async Client
FortuneClient.java
!
}
});
!
!
We’ll use ParSeqRestClient,
which can create Tasks from
Rest.li requests.

Async Client
FortuneClient.java
!
}
});
!
!
Here will compose together
two tasks, also in sequence
using Tasks.seq.

Async Client
FortuneClient.java
!
}
});
!
!
using Tasks.seq.
The getFortune task will
make a non-blocking request
to our /fortunes resource.

Async Client
FortuneClient.java
!
}
});
!
!
using Tasks.seq.
The getFortune task will
make a non-blocking request
to our /fortunes resource.
The printFortune task will
print the result of the
getFortune task to stdout.

Async Client
FortuneClient.java
!
}
});
!
!
We’ll use a ParSeq engine
directly here to execute the
async flow.

Async Client
FortuneClient.java
!
}
});
!
!
If our client is a command line
application, we need to wait
for our async tasks to
complete before exiting.

Run it again!

Run it again!
Much better. Now we can scale.

Next Steps
To learn more, try the
Rest.li Quickstart Tutorial
!
!
For more details on ParSeq,
see the ParSeq Wiki

Introduction to rest.li

More Related Content

What's hot

Viewers also liked

Similar to Introduction to rest.li

Recently uploaded

Introduction to rest.li