rest.li

Rest.li is an open source REST framework designed for building scalable RESTful architectures using type-safe bindings and asynchronous, non-blocking IO.

Core Features:

• End-to-end framework: Provides a complete development flow for building RESTful APIs.
• Non-blocking IO: Uses ParSeq for approachable asynchronous client and server code.
• Type-safety: Utilizes generated data and client bindings to ensure type-safe development.
• Annotation-driven: Server-side resource development is inspired by JAX-RS annotations.
• Scalability: Engineered for high availability and high scalability.
• Dynamic Discovery: An optional subsystem that provides client-side load balancing and fault tolerance.
• API Safety: Includes backward compatibility checking to ensure API changes are safe.
• Advanced REST capabilities: Supports batch operations, partial updates, and projections.
• API Catalog: Includes a Web UI for browsing and searching a catalog of Rest.li APIs.

In a D2 environment, services are organized into clusters. Coordination between clients and servers is achieved through Zookeeper.

Key components in the D2 architecture include:

• Clusters: Groups of service instances (e.g., RecommendationService, NewsService).
• Services: Logical endpoints within a cluster (e.g., articleRecommendation).
• d2Config.json: Defines the mapping of services to clusters. This is processed by the config-runner to populate Zookeeper.
• server.json: Configures the physical server instances (e.g., EchoServer) and assigns them to specific clusters.
• client.json: Configures the traffic proportions sent by the D2 client to various services.
• D2 Announcers: Components that register server availability in Zookeeper so clients can discover them.

Advanced D2 features include server weight adjustment, partition management, and routing stickiness.

The D2 framework provides several mechanisms for managing how clients interact with service clusters:

• Partitioning: Used to divide a service into distinct partitions (e.g., ProfileService). Each partition can contain specific servers, ensuring requests are routed to the correct subset of the cluster.
• Weighted Routing: Allows assigning different weights to servers within a partition (e.g., EmailService). Traffic is distributed according to these weights (e.g., a 10:1 ratio between two servers).
• Sticky Routing (Soft Affinity): Configures D2 to make an effort to route the same request to the same server to improve cache locality (e.g., CacheService). Note that this is not a strict guarantee; D2 may route to a different server if the primary target is in a bad state.
• Client Overrides: While services typically dictate client configuration (timeouts, connection pools, SSL), D2 allows clients to override these settings if the service permits it (e.g., BigDataService).

This example demonstrates how to use Guice 3 dependency injection with rest.li. To set up the environment, you must first propagate the PDSC and IDL changes from the repository root before building the specific Guice server example.

Prerequisites

• Gradle 4.6 or greater.
• If you prefer using a local wrapper, run ../../gradlew wrapper from the examples/guice-server directory to generate a ./gradlew script compatible with this sample.

Build Steps

1. Propagate IDL changes: From the repository root, run:

   gradle publishRestliIdl

2. Build the project: From the repository root, run:

   gradle build

   (Note: Subsequent builds only require gradle build after the initial IDL propagation).

Running the Server and Client

Navigate to the examples/guice-server folder to execute the following:

• Start the Jetty server:

  gradle JettyRunWar

• Test with a GET request (once the server is running):

  curl -v http://localhost:8080/fortunes/1

• Run the built-in client:

  gradle startFortunesClient

This example demonstrates advanced D2 client-server capabilities including partitioning, load balancing, weighted routing, client overrides, and sticky routing.

Prerequisites

• Ensure Zookeeper is running (default is localhost:2181).

Execution Steps

1. Populate Configuration: Run the config-runner to populate Zookeeper with the mappings defined in d2Config.json:

   ../../gradlew runConfigRunner

2. Start Servers: Create the echo servers and D2 announcers based on server.json:

   ../../gradlew runServer

   (Press Enter to stop the server)
3. Run Client Scenarios: You can run specific clients to observe different D2 behaviors:
   • ProfileService (Partitioning/Load Balancing): ../../gradlew runProfileClient
   • EmailService (Weighted Routing): ../../gradlew runEmailClient
   • BigDataService (Client Overrides): ../../gradlew runBigDataClient
   • CacheService (Sticky/Soft Affinity Routing): ../../gradlew runCacheClient