Path parameters

Path parameters are segments of the request path that can be parsed for usage in route handlers.

Example:

GET example.com/todo/1234?name=jaguar&message=hello&at=5

One of many applications of Path parameters is encoding ID of the resource being accessed. In the above example, a todo item with id 1234 is requested.

Defining path variable

Starting a path segment with character : informs Jaguar that this segment is a path variable.

  server.get('/api/quote/:index', (ctx) => ...);

The :index variable above will match anything except a slash. For example, /api/quote/123 and /api/quote/abc would both be matched by the route above.

All the path variables can be accessed using pathParams member of Context instance. pathParams is an instance of class PathParams.

main(List<String> args) async {
  final quotes = <String>[
    'But man is not made for defeat. A man can be destroyed but not defeated.',
    'When you reach the end of your rope, tie a knot in it and hang on.',
    'Learning never exhausts the mind.',
  ];

  final server = new Jaguar();
  server.get('/api/quote/:index', (ctx) {
    final int index = int.parse(ctx.pathParams['index']);
    return quotes[index + 1];
  });
  await server.serve();
}

Multiple path variables

There could be multiple variables in the same path.

main(List<String> args) async {
  final server = new Jaguar();
  server.get('/api/addition/:a/:b', (ctx) {
    final int a = int.parse(ctx.pathParams['a']);
    final int b = int.parse(ctx.pathParams['b']);
    return a + b;
  });
  await server.serve();
}

Given the request URL /api/addition/15/10, variables :a and :b shall match 15 and 10 respectively.

Type casting

Path variables can be converted to one of the supported target types (int, num, double and bool) using one of the get* methods.

main(List<String> args) async {
  final quotes = <String>[
    'But man is not made for defeat. A man can be destroyed but not defeated.',
    'When you reach the end of your rope, tie a knot in it and hang on.',
    'Learning never exhausts the mind.',
  ];

  final server = new Jaguar();
  server.get('/api/quote/:index', (ctx) {
    final int index = ctx.pathParams.getInt('index', 1);
    return quotes[index + 1];
  });
  await server.serve();
}

Path variable index is converted to int using int.parse function.

All these methods take an optional defaultValue argument, which is returned if the casting fails.

Glob path segment

A star can be used to match all the following path segments.

main(List<String> args) async {
  final server = new Jaguar();
  server.get('/api/1/*', (_) => new Response('Deprecated!', statusCode: 500));
  await server.serve();
}

The route handler will match any path that begins with /api/1/.

Captured Glob variable

Starred path variable can be used to match all the remaining path segments while also capturing the path segments it matches.

Example:

main(List<String> args) async {
  final server = new Jaguar();
  server.get(
      '/api/1/:path*',
      (ctx) => new Response('Deprecated! Use /api/2/${ctx.pathParams['path']}',
          statusCode: 500));
  await server.serve();
}

For example, the route handler will match any path beginning with /api/1/. The value of variable path will be the path sub-string that follows the matched /api/1/. If the request URL is /api/1/what/ever, path will hold what/ever.

References

• Route paths and path variables in Jaguar.dart

What's next

In the next article, We will explore accessing Query parameters in Jaguar.