Dart - api.post()

Register an API route and set a specific HTTP POST handler on that route.

This method is a convenient short version of api().route().post()

import 'package:nitric_sdk/nitric.dart';
// Create an API named 'public'
final api = Nitric.api("public");
api.post("/customers/:customerId", (ctx) async {
// Extract the path parameter
final id = ctx.req.pathParams["customerId"]!;
// Construct response for the POST: /customers request...
final responseBody = {};
ctx.res.json(responseBody);
return ctx;
});

Parameters

  • Name
    match
    Required
    Required
    Type
    String
    Description

    The path matcher to use for the route. Matchers accept path parameters in the form of a colon prefixed string. The string provided will be used as that path parameter's name when calling handlers.

  • Name
    handler
    Required
    Required
    Type
    HttpHandler
    Description

    The middleware service to use as the handler for HTTP requests.

  • Name
    security
    Optional
    Optional
    Type
    List<OidcOptions>
    Description

    Security rules to apply with scopes to the entire API.

  • Name
    middlewares
    Optional
    Optional
    Type
    List<HttpHandler>
    Description

    The list of middleware that will run before the handler is called. To call the next middleware in the chain use ctx.next(), to finish early return ctx by itself. The ordering of middleware goes: API -> Route -> Method.

Examples

Register a handler for POST requests

import 'package:nitric_sdk/nitric.dart';
// Create an API named 'public'
final api = Nitric.api("public");
api.post("/customers", (ctx) async {
// Construct response for the POST: /customers request...
final responseBody = {};
ctx.res.json(responseBody);
return ctx;
});

Chain services as a single method handler

When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using ctx.next(). If a middleware in the chain does not call .next and instead returns the base context, the call chain will end.

import 'package:nitric_sdk/nitric.dart';
Future<HttpContext> validate(HttpContext ctx) async {
if (!ctx.req.headers.containsKey("Content-Type")) {
ctx.res.status = 400;
ctx.res.body = "header Content-Type is required";
// End the middleware chain by not calling `ctx.next()`.
return ctx;
}
return ctx.next();
}
Future<HttpContext> createCustomer(HttpContext ctx) async {
// handle the POST request...
return ctx.next();
}
// The validate middleware will run before the createCustomer handler
Nitric.api("public").post("/customers", createCustomer, middlewares: [validate]);

Access the request body

The POST request body is accessible from the ctx.req object.

import 'package:nitric_sdk/nitric.dart';
// Create an API named 'public'
final api = Nitric.api("public");
api.post("/customers/:customerId", (ctx) async {
// Extract the path parameter
final id = ctx.req.pathParams["customerId"]!;
// Extract the request body
final customerData = ctx.req.json();
// Construct response for the PATCH: /customers request...
final responseBody = {};
ctx.res.json(responseBody);
return ctx;
});
Last updated on Dec 5, 2024