Skip to content
MAATDocumentationLatest

Build Your First Maat Application

In this guide, you will create a Maat application with a small JSON endpoint, validate its input, and test the complete request flow. You only need the Dart SDK—Maat does not require Node.js, reflection, or code generation.

Create the Application

Install Ptah, Maat’s project installer, and create an application named blog:

Terminal window
dart pub global activate ptah
maat new blog
cd blog

Ptah installs the application’s Dart packages, creates .env, and generates an application key. The generated project already includes a health route and a passing feature test.

Add a Validated Route

Replace routes/api.dart with the following code:

import 'package:maat/maat.dart';


/// Routes served under `/api`.
void apiRoutes() {
  Route.get('/health', (Request request) => {'status': 'ok'});


  Route.post('/posts', (Request request) async {
    final data = await request.validate({'title': 'required|string|max:120'});


    return Response.json({'data': data}, status: 201);
  });
}

The route is available at /api/posts because the generated RouteServiceProvider applies the /api prefix. request.validate() returns only validated fields and automatically produces a 422 JSON response when the title is missing or longer than 120 characters.

Test the Endpoint

Create test/feature/posts_test.dart:

import 'package:maat/testing.dart';
import 'package:test/test.dart';


import '../../bootstrap/app.dart';


void main() {
  test('creates a validated post', () async {
    final client = TestClient(await createApp());


    (await client.postJson('/api/posts', {
      'title': 'First Maat post',
    })).assertCreated().assertJson({
      'data': {'title': 'First Maat post'},
    });


    (await client.postJson('/api/posts', {
      'title': '',
    })).assertUnprocessable().assertJsonValidationErrors(['title']);
  });
}

Run the test:

Terminal window
dart test test/feature/posts_test.dart

TestClient sends requests directly through Maat’s HTTP kernel, so the test does not open a port or depend on an external server.

Run the Application

Start the development server:

Terminal window
maat serve

In another terminal, send a valid request:

Terminal window
curl -X POST http://127.0.0.1:8000/api/posts \
  -H 'content-type: application/json' \
  -d '{"title":"First Maat post"}'

Maat returns a 201 Created response:

{"data":{"title":"First Maat post"}}

Where to Go Next