Skip to main content

What is the REST Transport?

The REST transport automatically creates standard HTTP endpoints from your service methods. It uses naming conventions to determine HTTP methods (GET, POST, PUT, DELETE) and paths, so you don’t need to write routing code. REST is the most familiar protocol for web APIs. It’s what you use when calling APIs with curl, fetch in JavaScript, or any HTTP client.

Quick Start

Mount your service with the REST transport:
Your service now has these endpoints:

Method Name to HTTP Mapping

Contract automatically maps method names to HTTP verbs:

Examples

Mount Options

Mount

Mount all routes directly on the router:

MountAt

Mount routes under a prefix:

Getting Routes

Get route definitions without mounting:

Making Requests

Create (POST)

Response:

List (GET)

Response:

Get (GET with ID)

Response:

Update (PUT)

Response:

Delete (DELETE)

Response: HTTP 204 No Content (empty body)

Path Parameters

For methods that need an ID from the URL path, use the path tag:

Multiple Path Parameters

For nested resources:
Register with custom HTTP binding:

Query Parameters

By default, input comes from the request body. For GET requests, you may want query parameters:
Request:

Custom HTTP Bindings

Override the automatic HTTP mapping with WithMethodHTTP:
Or set multiple bindings at once:

Complete Example

This example shows a complete REST service using the recommended package-based organization:

Error Responses

Use Contract errors for proper HTTP status codes:
Error response format:

Multiple Services

Mount multiple services on the same router:

Using with Middleware

Apply middleware to your routes:

OpenAPI Documentation

Generate OpenAPI spec from your service:
See the OpenAPI documentation for more details.

Common Questions

How do I change the path for a method?

Use WithMethodHTTP:

How do I add query parameters?

Use the query tag on input struct fields:

Can I use different content types?

By default, REST uses application/json. For other content types, use standard mizu handlers instead of Contract.

How do I handle file uploads?

File uploads aren’t currently supported through Contract. Use standard mizu file handling for upload endpoints.

How do I add authentication?

Use mizu middleware to add authentication before requests reach your service methods. See Mizu Middleware documentation.

What’s Next?