English

Español

English

Español

Appearance

HTTP Response Handling ​

In Sword, the recommended way to respond from a web controller is using JsonResponse or WebResult.

Common Return Types ​

rust
use sword::prelude::*;
use sword::web::*;

#[get("/")]
async fn health(&self) -> JsonResponse {
    JsonResponse::Ok().message("Service available")
}
rust
use sword::prelude::*;
use sword::web::*;

#[get("/{id}")]
async fn get_user(&self, req: Request) -> WebResult {
    let id = req.param::<u64>("id")?;

    Ok(JsonResponse::Ok().data(id))
}
  • JsonResponse
  • WebResult

WebResult ​

WebResult is an alias for:

rust
Result<JsonResponse, JsonResponse>

This allows you to return both successful and error responses using the framework's standardized JSON format.

JsonResponse ​

JsonResponse is the primary struct for building JSON responses in Sword.

Common Constructors ​

  • JsonResponse::Ok()
  • JsonResponse::Created()
  • JsonResponse::BadRequest()
  • JsonResponse::Unauthorized()
  • JsonResponse::NotFound()
  • JsonResponse::InternalServerError()

Minimal Example ​

rust
use sword::prelude::*;
use sword::web::*;

async fn example() -> JsonResponse {
    JsonResponse::Ok().message("Successful operation")
}

Payload Construction ​

message()

Adds a descriptive message to the response.

rust
let response = JsonResponse::Ok().message("Successful operation");
data()

Attaches any serializable value.

rust
use serde::Serialize;

#[derive(Serialize)]
struct MyData {
    field1: String,
    field2: u32,
}

let response = JsonResponse::Ok().data(MyData {
    field1: "value".to_string(),
    field2: 42,
});
error()

Attaches a single error message.

rust
let response = JsonResponse::BadRequest().error("Invalid input data");
errors()

Attaches a collection of errors or a validation structure.

rust
let response = JsonResponse::BadRequest().errors(vec!["Error 1", "Error 2"]);

Controller Example ​

rust
use sword::prelude::*;
use sword::web::*;

#[controller(kind = Controller::Web, path = "/users")]
pub struct UsersController;

impl UsersController {
    #[get("/")]
    async fn list_users(&self) -> JsonResponse {
        JsonResponse::Ok().message("Users list")
    }
}
rust
use sword::prelude::*;
use sword::web::*;

#[controller(kind = Controller::Web, path = "/users")]
pub struct UsersController;

impl UsersController {
    #[get("/{id}")]
    async fn get_by_id(&self, req: Request) -> WebResult {
        let id = req.param::<u64>("id")?;

        Ok(JsonResponse::Ok().data(id))
    }
}

Automatic Errors from Request ​

Many Request methods return a RequestError, and Sword converts them into JSON responses when you use WebResult.

Common methods include:

  • req.param::<T>(...)
  • req.body::<T>()
  • req.query::<T>()
  • req.body_validator::<T>()

Can I return something else? ​

Yes. A controller can also return any type that implements IntoResponse, as Sword's web layer is built on top of Axum.

However, JsonResponse and WebResult remain the recommended choice if you want to maintain the framework's standard response format.

See Also ​