Quickstart — Your First Blueprint in 15 Minutes

Go from cluster login to a live Hello World page and a JSON API endpoint — created, activated, and tested with blueprints, without writing backend code.

In this quickstart you build two things on your cluster: a page that renders "Hello World" in the browser, and an API endpoint that returns it as JSON. Along the way you practice the four moves every RUAL developer uses daily: creating a blueprint, placing and connecting blocks, activating, and testing in development view.

1. Prerequisites

Before you start, you need:

• A cluster URL — the address of the RUAL cluster you will build on.
• A username and password authorized for RUAL Studio access. If you don't have an account yet, an existing administrator creates one for you — see Getting Access.

You work in RUAL Studio, the web application at rual.at. Log in with your cluster URL and credentials to open your cluster.

2. Create Your First Blueprint

All logic in RUAL lives in blueprints — large canvases where you place blocks and connect them into flows. Open the blueprints overview in RUAL Studio and create a new blueprint. RUAL first asks what type of blueprint you would like; the chosen type pre-arranges the canvas with the right starting blocks.

1. Choose Build a UI Page — this seeds the canvas with a state_page block, the starting block of every page flow.
2. Give the blueprint a clear name, for example Hello World Page. One blueprint per component is the convention, similar to assigning a single class to a file in traditional coding.
3. The canvas opens. Set the URL on the state_page block, for example /hello-world.

3. Build the Page

A page flow needs a render block and at least one element to display. You will use four blocks:

Now wire them together:

1. Add the render block. Left-click the flow out-pin of state_page, drag into an empty area of the canvas, and pick render from the search results — the connection is established automatically. Also drag the Connection out-pin onto the render block's connection in-pin.
2. Set title and description. The render block requires a title and a description. Right-click the canvas, choose Add new block, add a value_default block for each, and connect them.
3. Add the heading. Add a state_h1 block the same way and connect its state out-pin to the render block's content in-pin.
4. Set the text. Add one more value_default block, type Hello World into it, and connect it to the h1 block's text in-pin.
5. Save. Use the Save button in the bottom bar, or Cmd/Ctrl + S.

You just used the two connection kinds every blueprint is built from. flow pins control when a block runs — the execution order. Data pins such as value, object, and state carry what a block works on. You can only connect pins of compatible types — read more in Block Execution.

4. Activate and Test

Pages, APIs, and modals are inactive by default. Click Activate in the top bar of the blueprint to make your page respond.

Then test the page in your browser:

1. Open the page from RUAL Studio. Studio automatically redirects you with the ?development query, so with a RUAL Developer account you see your saved — not yet deployed — blueprint.
2. You should see a plain page with your Hello World heading. If not, check that you saved and activated the blueprint.
3. To execute the non-deployed blueprint against production data, select Production Run within your blueprint.

Visitors only see the page after you deploy it to production. Saving keeps changes in development; deploying is a separate step — see How to Deploy.

5. Your First API Endpoint

An API endpoint is a blueprint too. Create a new blueprint of type Build an API endpoint and name it, for example, Hello World API. The canvas is seeded with an on_startup_register_uri_get block, which exposes a GET URI under /api/. Set the URI to hello-world — your endpoint becomes /api/hello-world.

Build the response flow with these blocks:

1. Create the handler function. Drag from the On Request out-pin into an empty area and create a function — name it, for example, hello_world. Its flow out-pin runs on every request.
2. Add the reply block. Add a httpconnection_set_json block and connect the function's flow out-pin to its flow in-pin.
3. Connect the request. Add a httpconnection_current_request block and connect it to the connection in-pin.
4. Set the status code. Add a number_default block with 200 and connect it to the code in-pin.
5. Build the JSON body. Add an object_new_fields block with a field message, connect a value_default holding Hello World to that field, and connect the object out-pin to the data in-pin — objects are cast to a JSON value automatically.
6. Save and activate. Cmd/Ctrl + S, then Activate in the top bar.

Call your endpoint from any terminal:

curl https://<your-cluster>/api/hello-world

{
  "message": "Hello World"
}

New pages and APIs use the *public scope by default, so anyone can call them. To restrict access, click the lock icon on the block to open the Scopes Management Modal and assign scopes — see Remote Access Control. Your cluster also ships 40+ built-in REST APIs for managing blueprints, users, and storage, documented under Cluster APIs.

6. Next Steps

You created two blueprints, wired flow and data pins, activated a page and an API, and tested both. Where to go from here:

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem