Home

What is Rest.li?

Rest.li is a REST+JSON framework for building robust, scalable service architectures using dynamic discovery and simple asynchronous APIs.

Rest.li fills a niche for building RESTful service architectures at scale, offering a developer workflow for defining data and REST APIs that promotes uniform interfaces, consistent data modeling, type-safety, and compatibility checked API evolution.

No, Really. What is Rest.li?

Oh, you want to see some code, don't you?

Basically, Rest.li is a framework where you define schema's for your data:

{
  "name" : "Greeting", "namespace" : "com.example.greetings", "type" : "record",
  "fields" : [
    { "name" : "message", "type" : "string" }
  ]
}

Write servers:

@RestLiCollection(name = "greetings")
class GreetingsResource extends CollectionResourceTemplate<Long, Message> {
  public Greeting get(Long key) {
    return new Greeting().setMessage("Good morning!");
  }
}

And then write clients:

Response<Greeting> response = restClient.sendRequest(new GreetingsBuilders.get().id(1L).build()).get();
System.out.println(response.getEntity().getMessage());

And get all the benefits of a robust, scalable REST+JSON framework.

Quickstart Guides and Examples

• Quickstart Guide - a step-by-step tutorial on the basics

Design Principles

• Promote uniform interfaces through consistent data modeling and REST conventions
• Seamlessly integrate a JSON serializable data layer including a data schema language and generated language bindings
• Provide published interface definitions, generated from server code
• Make calling services dead simple with generated type-safe client bindings
• Versioning with automated compatibility checking
• Simple asynchronous API
• Dynamic discovery with load balancing

Requirements

• Java 1.6+
• Gradle 1.2+

Documentation

• Rest.li
  • Architecture Intro
    • Server-side Data Flow
    • Client-side Data Flow
    • Development Flow
  • Server
    • Resources
    • Resource Types
    • Base Operations
      • Create
      • Get
      • Update
      • Delete
    • Finders
    • Actions
  • Client
  • Projections
  • Tools
    • IDL generation
    • Client binding generation
    • Gradle build integration
• Data Schema and Templates
• Dynamic Discovery (D2)
• Request/Response (R2)
• FAQs
  • Data FAQ
• [Checking Out/Building] (wiki/Building-with-Rest.li)
• How to Contribute

Components

Rest.li is the top layer of a larger software stack code named 'pegasus'. Pegasus is comprised of the following major components:

data/

The pegasus data layer, which provides an in-memory data representation structurally equivalent to JSON, serialization to/from JSON format, and a schema-definition language for specifying data format.

generator/

The pegasus data template code generation tool, which generates type-safe Java APIs for manipulating pegasus data objects.

r2/

The pegasus request/response layer, which provides fully asynchronous abstractions for transport protocols, along with implementations for HTTP based on Netty and Jetty.

d2/

The pegasus dynamic discovery layer, which uses Apache Zookeeper to maintain cluster information. D2 provides client-side software load balancing.

restli-*/

The pegasus Rest.li framework, which provides a simple framework for building and consuming RESTful resources. Rest.li provides resource patterns which streamline common CRUD use cases for collections of entities and associations between entities.