Make readme's easier to navigate and read (#80)

* Make table instead of current list of examples * Add download commands to the READMEs * Add patterns to list, and improve typescript readme * Fix links in typescript readme * Improve Readme structures * Fix Readme's for Java and Kotlin examples * Fix bug in readme
restatedev · Jan 30, 2024 · 390ceda · 390ceda
1 parent d22ac6d
commit 390ceda
Show file tree

Hide file tree

Showing 19 changed files with 285 additions and 151 deletions.
diff --git a/README.md b/README.md
@@ -7,107 +7,35 @@
 Browse this repository to see how easy distributed applications development becomes with Restate.
 
 ## Starters
-
-![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
-
-[Hello world on AWS Lambda](typescript/hello-world-lambda)
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-hello-world-lambda.zip && unzip typescript-hello-world-lambda.zip -d typescript-hello-world-lambda && rm typescript-hello-world-lambda.zip
-```
-
-![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
-
-[Hello world on AWS Lambda + CDK](typescript/hello-world-lambda-cdk)
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-hello-world-lambda-cdk.zip && unzip typescript-hello-world-lambda-cdk.zip -d typescript-hello-world-lambda-cdk && rm typescript-hello-world-lambda-cdk.zip
-```
-
-![Java](https://img.shields.io/badge/java-%23ED8B00.svg?style=for-the-badge&logo=openjdk&logoColor=white)
-
-[Hello World HTTP](java/hello-world-http)
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-http.zip && unzip java-hello-world-http.zip -d java-hello-world-http && rm java-hello-world-http.zip
-```
-
-[Hello world on AWS Lambda](java/hello-world-lambda)
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-lambda.zip && unzip java-hello-world-lambda.zip -d java-hello-world-lambda && rm java-hello-world-lambda.zip
-```
-
-![Kotlin](https://img.shields.io/badge/kotlin-%237F52FF.svg?style=for-the-badge&logo=kotlin&logoColor=white)
-
-[Hello World HTTP](kotlin/hello-world-http)
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-http.zip && unzip kotlin-hello-world-http.zip -d kotlin-hello-world-http && rm kotlin-hello-world-http.zip
-```
-
-[Hello world on AWS Lambda](kotlin/hello-world-lambda)
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-lambda.zip && unzip kotlin-hello-world-lambda.zip -d kotlin-hello-world-lambda && rm kotlin-hello-world-lambda.zip
-```
-
-[Hello world on AWS Lambda + CDK](kotlin/hello-world-lambda-cdk)
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-lambda-cdk.zip && unzip kotlin-hello-world-lambda-cdk.zip -d kotlin-hello-world-lambda-cdk && rm kotlin-hello-world-lambda-cdk.zip
-```
+| Language  | Name / Link                                                     |
+|-----------|-----------------------------------------------------------------|
+| TypeScript| [Hello world on AWS Lambda](typescript/hello-world-lambda)       |
+| TypeScript| [Hello world on AWS Lambda + CDK](typescript/hello-world-lambda-cdk) |
+| Java      | [Hello World HTTP](java/hello-world-http)                       |
+| Java      | [Hello world on AWS Lambda](java/hello-world-lambda)             |
+| Kotlin    | [Hello World HTTP](kotlin/hello-world-http)                     |
+| Kotlin    | [Hello world on AWS Lambda](kotlin/hello-world-lambda)           |
+| Kotlin    | [Hello world on AWS Lambda + CDK](kotlin/hello-world-lambda-cdk) |
 
 ## Patterns
 
-![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
-
-[Payment api](typescript/payment-api): Example API for payments, inspired by the Stripe API
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-payment-api.zip && unzip typescript-payment-api.zip -d typescript-payment-api && rm typescript-payment-api.zip
-```
+| Language   | Name / Link                                                                                                             |
+|------------|-------------------------------------------------------------------------------------------------------------------------|
+| TypeScript | [Payment API](typescript/payment-api): Example API for payments, inspired by the Stripe API                             |
+| TypeScript | [End-to-end testing](typescript/end-to-end-testing): Example of how to test Restate services end-to-end                 |
+| TypeScript | [Common patterns](typescript/patterns) Set of common patterns you encounter when developing distributed TS applications |
+| Java       | [Common patterns](java/patterns) Set of common patterns you encounter when developing distributed Java applications     |
 
-[End-to-end testing](typescript/end-to-end-testing): Example of how to test Restate services end-to-end
-```shell
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-end-to-end-testing.zip && unzip typescript-end-to-end-testing.zip -d typescript-end-to-end-testing && rm typescript-end-to-end-testing.zip
-```
 
 ## Applications
 
-![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
-
-[Food ordering - TypeScript](typescript/food-ordering): Integrate Restate with external services
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-food-ordering.zip && unzip typescript-food-ordering.zip -d typescript-food-ordering && rm typescript-food-ordering.zip
-```
-
-[Ticket reservation](typescript/ticket-reservation): Example showing Restate's keyed-sharding and concurrency guarantees
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-ticket-reservation.zip && unzip typescript-ticket-reservation.zip -d typescript-ticket-reservation && rm typescript-ticket-reservation.zip
-```
-
-[Ecommerce store](typescript/ecommerce-store): An ecommerce store completely built on top of Restate
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-ecommerce-store.zip && unzip typescript-ecommerce-store.zip -d typescript-ecommerce-store && rm typescript-ecommerce-store.zip
-```
-
-[Dynamic workflow executor](typescript/dynamic-workflow-executor): A workflow executor that dynamically executes a list of steps as specified in the JSON input.
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/typescript-dynamic-workflow-executor.zip && unzip typescript-dynamic-workflow-executor.zip -d typescript-dynamic-workflow-executor && rm typescript-dynamic-workflow-executor.zip
-```
-
-![Java](https://img.shields.io/badge/java-%23ED8B00.svg?style=for-the-badge&logo=openjdk&logoColor=white)
-
-[Food ordering - Java](java/food-ordering): Java food order processing app and driver-to-delivery matching services.
-```shell
-# Download the example
-wget https://github.com/restatedev/examples/releases/latest/download/java-food-ordering.zip && unzip java-food-ordering.zip -d java-food-ordering && rm java-food-ordering.zip
-```
+| Language  | Name / Link                                                     |
+|-----------|-----------------------------------------------------------------|
+| TypeScript| [Food ordering - TypeScript](typescript/food-ordering): Integrate Restate with external services |
+| TypeScript| [Ticket reservation](typescript/ticket-reservation): Example showing Restate's keyed-sharding and concurrency guarantees |
+| TypeScript| [Ecommerce store](typescript/ecommerce-store): An ecommerce store completely built on top of Restate |
+| TypeScript| [Dynamic workflow executor](typescript/dynamic-workflow-executor): A workflow executor that dynamically executes a list of steps as specified in the JSON input |
+| Java      | [Food ordering - Java](java/food-ordering): Java food order processing app and driver-to-delivery matching services |
 
 
 ## Joining the community

diff --git a/java/README.md b/java/README.md
@@ -2,14 +2,21 @@
 
 This directory contains Restate examples using the Java SDK.
 
-## Common patterns
+## Starters
+| Language  | Name / Link                                                     |
+|-----------|-----------------------------------------------------------------|
+| Java      | [Hello World HTTP](hello-world-http)                       |
+| Java      | [Hello world on AWS Lambda](hello-world-lambda)             |
 
-- A collection of [common patterns](patterns) you encounter when developing distributed applications.
+## Patterns
 
-## Starter examples
+| Language   | Name / Link                                                                                                             |
+|------------|-------------------------------------------------------------------------------------------------------------------------|
+| Java       | [Common patterns](patterns) Set of common patterns you encounter when developing distributed Java applications     |
 
-- [Hello World](hello-world-http): A simple example of a Restate service.
-- [Hello World - AWS Lambda](hello-world-lambda): A simple example of how you can run a Restate service on AWS Lambda.
 
 ## Applications
-- [Food ordering](food-ordering): See how to integrate Restate with external services using Awakeables and side effects.
+
+| Language  | Name / Link                                                     |
+|-----------|-----------------------------------------------------------------|
+| Java      | [Food ordering - Java](food-ordering): Java food order processing app and driver-to-delivery matching services |
diff --git a/java/food-ordering/README.md b/java/food-ordering/README.md
@@ -8,7 +8,24 @@ It also interacts with the delivery services to get the order delivered to the c
 
 ![demo_overview.png](demo_overview.png)
 
-
+## Download the example
+
+- Via the CLI:
+    ```shell
+    restate example java-food-ordering && cd java-food-ordering
+    ```
+
+- Via git clone:
+    ```shell
+    git clone [email protected]:restatedev/examples.git
+    cd examples/java/food-ordering
+    ```
+
+- Via `wget`:
+    ```shell
+   wget https://github.com/restatedev/examples/releases/latest/download/java-food-ordering.zip && unzip java-food-ordering.zip -d java-food-ordering && rm java-food-ordering.zip
+    ```
+
 ## Running locally with Docker compose
 
 Build the docker containers:

diff --git a/java/hello-world-http/README.md b/java/hello-world-http/README.md
@@ -10,9 +10,21 @@ Sample project configuration of a Restate service using the Java interface and H
 
 ## Download the example
 
-```shell
-wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-http.zip && unzip java-hello-world-http.zip -d java-hello-world-http && rm java-hello-world-http.zip
-```
+- Via the CLI:
+    ```shell
+    restate example java-hello-world-http && cd java-hello-world-http
+    ```
+
+- Via git clone:
+    ```shell
+    git clone [email protected]:restatedev/examples.git
+    cd examples/java/hello-world-http
+    ```
+
+- Via `wget`:
+    ```shell
+    wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-http.zip && unzip java-hello-world-http.zip -d java-hello-world-http && rm java-hello-world-http.zip
+    ```
 
 ## Running the example
 

diff --git a/java/hello-world-lambda/README.md b/java/hello-world-lambda/README.md
@@ -10,10 +10,21 @@ Sample project configuration of a Restate service using the Java interface and A
 * [Logging configuration](src/main/resources/log4j2.properties)
 
 ## Download the example
-
-```shell
-wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-lambda.zip && unzip java-hello-world-lambda.zip -d java-hello-world-lambda && rm java-hello-world-lambda.zip
-```
+- Via the CLI:
+    ```shell
+    restate example java-hello-world-lambda && cd java-hello-world-lambda
+    ```
+
+- Via git clone:
+    ```shell
+    git clone [email protected]:restatedev/examples.git
+    cd examples/java/hello-world-lambda
+    ```
+
+- Via `wget`:
+    ```shell
+    wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-lambda.zip && unzip java-hello-world-lambda.zip -d java-hello-world-lambda && rm java-hello-world-lambda.zip
+    ```
 
 ## Package
 

diff --git a/kotlin/README.md b/kotlin/README.md
@@ -0,0 +1,10 @@
+# Kotlin examples
+
+This directory contains Restate examples using the Kotlin SDK.
+
+## Starters
+| Language  | Name / Link                                                     |
+|-----------|-----------------------------------------------------------------|
+| Kotlin    | [Hello World HTTP](hello-world-http)                     |
+| Kotlin    | [Hello world on AWS Lambda](hello-world-lambda)           |
+| Kotlin    | [Hello world on AWS Lambda + CDK](hello-world-lambda-cdk) |
diff --git a/kotlin/hello-world-http/README.md b/kotlin/hello-world-http/README.md
@@ -10,9 +10,21 @@ Sample project configuration of a Restate service using the Kotlin coroutines in
 
 ## Download the example
 
-```shell
-wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-http.zip && unzip kotlin-hello-world-http.zip -d kotlin-hello-world-http && rm kotlin-hello-world-http.zip
-```
+- Via the CLI:
+    ```shell
+    restate example kotlin-hello-world-http && cd kotlin-hello-world-http
+    ```
+
+- Via git clone:
+    ```shell
+    git clone [email protected]:restatedev/examples.git
+    cd examples/kotlin/hello-world-http
+    ```
+
+- Via `wget`:
+    ```shell
+    wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-http.zip && unzip kotlin-hello-world-http.zip -d kotlin-hello-world-http && rm kotlin-hello-world-http.zip
+    ```
 
 ## Running the example
 

diff --git a/kotlin/hello-world-lambda-cdk/README.md b/kotlin/hello-world-lambda-cdk/README.md
@@ -12,9 +12,21 @@ For more information on CDK, please see [Getting started with the AWS CDK](https
 
 ## Download the example
 
-```shell
-wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-lambda-cdk.zip && unzip kotlin-hello-world-lambda-cdk.zip -d kotlin-hello-world-lambda-cdk && rm kotlin-hello-world-lambda-cdk.zip
-```
+- Via the CLI:
+    ```shell
+    restate example kotlin-hello-world-lambda-cdk && cd kotlin-hello-world-lambda-cdk
+    ```
+
+- Via git clone:
+    ```shell
+    git clone [email protected]:restatedev/examples.git
+    cd examples/kotlin/hello-world-lambda-cdk
+    ```
+
+- Via `wget`:
+    ```shell
+    wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-lambda-cdk.zip && unzip kotlin-hello-world-lambda-cdk.zip -d kotlin-hello-world-lambda-cdk && rm kotlin-hello-world-lambda-cdk.zip
+    ```
 
 ## Deploy
 

diff --git a/kotlin/hello-world-lambda/README.md b/kotlin/hello-world-lambda/README.md
@@ -11,9 +11,21 @@ Sample project configuration of a Restate service using the Kotlin coroutines in
 
 ## Download the example
 
-```shell
-wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-lambda.zip && unzip kotlin-hello-world-lambda.zip -d kotlin-hello-world-lambda && rm kotlin-hello-world-lambda.zip
-```
+- Via the CLI:
+    ```shell
+    restate example kotlin-hello-world-lambda && cd kotlin-hello-world-lambda
+    ```
+
+- Via git clone:
+    ```shell
+    git clone [email protected]:restatedev/examples.git
+    cd examples/kotlin/hello-world-lambda
+    ```
+
+- Via `wget`:
+    ```shell
+    wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-lambda.zip && unzip kotlin-hello-world-lambda.zip -d kotlin-hello-world-lambda && rm kotlin-hello-world-lambda.zip
+    ```
 
 ## Package
 

diff --git a/typescript/README.md b/typescript/README.md
@@ -2,21 +2,26 @@
 
 This directory contains Restate examples using the Typescript SDK.
 
-## Common patterns
+## Starters
+| Language  | Name / Link                                                     |
+|-----------|-----------------------------------------------------------------|
+| TypeScript| [Hello world on AWS Lambda](hello-world-lambda)       |
+| TypeScript| [Hello world on AWS Lambda + CDK](hello-world-lambda-cdk) |
 
-- A collection of [common patterns](patterns) you encounter when developing distributed applications.
+## Patterns
 
-## Starter examples
+| Language  | Name / Link                                                                                                  |
+|-----------|--------------------------------------------------------------------------------------------------------------|
+| TypeScript| [Payment API](payment-api): Example API for payments, inspired by the Stripe API                             |
+| TypeScript| [End-to-end testing](end-to-end-testing): Example of how to test Restate services end-to-end                 |
+| TypeScript| [Common patterns](patterns) Set of common patterns you encounter when developing distributed TS applications |
 
-- [Hello World - AWS Lambda](hello-world-lambda): A simple example of how you can run a Restate service on AWS Lambda.
-- [Hello World - AWS Lambda & CDK](hello-world-lambda-cdk): A simple example of automating deployment to AWS Lambda using CDK.
-- [Payment api](payment-api/): Example API for payments, inspired by the Stripe API.
-- [Food ordering](food-ordering): See how to integrate Restate with external services using Awakeables and side effects.
 
-## Intermediate examples
+## Applications
 
-- [Ticket reservation](ticket-reservation): An example to illustrate how Restate's keyed-sharding and concurrency guarantees simplify microservice architectures.
-
-## Advanced examples
-
-- [Ecommerce store](ecommerce-store): A sophisticated example on how to build an ecommerce store based on Restate using the grpc-based Typescript SDK.
+| Language  | Name / Link                                                     |
+|-----------|-----------------------------------------------------------------|
+| TypeScript| [Food ordering - TypeScript](food-ordering): Integrate Restate with external services |
+| TypeScript| [Ticket reservation](ticket-reservation): Example showing Restate's keyed-sharding and concurrency guarantees |
+| TypeScript| [Ecommerce store](ecommerce-store): An ecommerce store completely built on top of Restate |
+| TypeScript| [Dynamic workflow executor](dynamic-workflow-executor): A workflow executor that dynamically executes a list of steps as specified in the JSON input |
diff --git a/typescript/dynamic-workflow-executor/README.md b/typescript/dynamic-workflow-executor/README.md
@@ -24,6 +24,24 @@ Here is an overview of the services:
 **Note:** This app stores images locally in the shared locally accessible folder `generated-images`.
 In a real deployment, this would need to be a shared storage, like S3.
 
+## Download the example
+
+- Via the CLI:
+    ```shell
+    restate example typescript-dynamic-workflow-executor && cd typescript-dynamic-workflow-executor
+    ```
+
+- Via git clone:
+    ```shell
+    git clone [email protected]:restatedev/examples.git
+    cd examples/typescript/dynamic-workflow-executor
+    ```
+
+- Via `wget`:
+    ```shell
+    wget https://github.com/restatedev/examples/releases/latest/download/typescript-dynamic-workflow-executor.zip && unzip typescript-dynamic-workflow-executor.zip -d typescript-dynamic-workflow-executor && rm typescript-dynamic-workflow-executor.zip
+    ```
+
 ## Running the example
 
 ### Deploy Restate Server