Getting Started

Installation

Add Crate as a dependency in your dub.json:

{
  "dependencies": {
    "crate": "~>1.0"
  }
}

Or in dub.sdl:

dependency "crate" version="~>1.0"

Crate depends on vibe.d, which will be pulled in automatically.

Your First API

1. Define a Model

A Crate model is a plain D struct with a string _id field:

struct Product {
  string _id;
  string name;
  int price;
}

The _id field is the primary key. Crate uses it for item-level operations like GET, PUT, PATCH, and DELETE.

2. Create a Crate and Router

import crate.http.router;
import crate.collection.memory;
import vibe.http.router;

void main() {
  auto router = new URLRouter();
  auto products = new MemoryCrate!Product;
  router.crateSetup!RestApi.add(products);
  router.run();
}

3. Test It

Start your application and use curl to interact with the API:

# Create a product
curl -X POST http://localhost:8080/products \
  -H "Content-Type: application/json" \
  -d '{"product": {"name": "Widget", "price": 42}}'

# List all products
curl http://localhost:8080/products

# Get a specific product
curl http://localhost:8080/products/000000000000000000000001

# Update a product
curl -X PATCH http://localhost:8080/products/000000000000000000000001 \
  -H "Content-Type: application/json" \
  -d '{"product": {"price": 50}}'

# Replace a product
curl -X PUT http://localhost:8080/products/000000000000000000000001 \
  -H "Content-Type: application/json" \
  -d '{"product": {"name": "Super Widget", "price": 99}}'

# Delete a product
curl -X DELETE http://localhost:8080/products/000000000000000000000001

Notice the request body wraps the data in a key matching the model name ("product"). The REST API policy uses this convention for both requests and responses.

Using MongoDB

For production, replace MemoryCrate with MongoCrate:

import crate.collection.mongo;

auto products = new MongoCrate!Product("products_collection");

The MongoCrate constructor takes the MongoDB collection name. It uses the same interface as MemoryCrate, so the rest of your code stays the same.

Route Naming

Crate automatically generates route paths from your struct name:

Struct Name	List Path	Item Path
Product	/products	/products/:id
User	/users	/users/:id
MapFile	/mapfiles	/mapfiles/:id
SiteSubset	/sitesubsets	/sitesubsets/:id

The path is the struct name lowercased with an “s” appended.

Adding Multiple Models

Chain multiple add() calls on the same router:

auto crateRouter = router.crateSetup!RestApi;

crateRouter.add(productCrate);
crateRouter.add(userCrate);
crateRouter.add(orderCrate);

Or use prepare() for models that need custom configuration:

crateRouter.add(productCrate);  // Simple model

crateRouter
  .prepare(userCrate)           // Complex model
  .and(authMiddleware)
  .and(validationFilter);

Next Steps

• Learn about model conventions and CRUD behavior
• Add middleware for authentication, filtering, and validation
• Create custom operations beyond standard CRUD