# Requests & Responses

* [Requests and Responses](/guides/requests-and-responses.md#requests-and-responses)
  * [Return Values](/guides/requests-and-responses.md#return-values)
  * [Other Parameters](/guides/requests-and-responses.md#other-parameters)
  * [Queries, Files and Bodies](/guides/requests-and-responses.md#queries-files-and-bodies)
* [Next Up...](/guides/requests-and-responses.md#next-up)

## Requests and Responses

Angel is inspired by Express, and such, request handlers in general resemble those from Express. Request handlers can return any Dart object (see [how they are handled](/guides/requests-and-responses.md#return-values)). Basic request handlers accept two parameters:

* [`RequestContext`](https://www.dartdocs.org/documentation/angel_framework/latest/angel_framework/RequestContext-class.html) - Contains vital information about the client requesting a resource, such as request method, request body, IP address, etc. The request object can also be used to pass information from one handler to the next. 
* [`ResponseContext`](https://www.dartdocs.org/documentation/angel_framework/latest/angel_framework/ResponseContext-class.html) - Allows you to send headers, write data, and more, to be sent to the client. To prevent a response from being modified by future handlers, call `res.end()` to prevent further writing.

### Return Values

Request handlers can return any Dart value. Return values are handled as follows:

* If you return a `bool`: Request handling will end prematurely if you return `false`, but it will continue if you return `true`.
* If you return `null`: Request handling will continue, unless you closed the response object by calling [`res.close()`](https://www.dartdocs.org/documentation/angel_framework/latest/angel_framework/ResponseContext/close.html). Some response methods, such as [`res.redirect()`](https://www.dartdocs.org/documentation/angel_framework/latest/angel_framework/ResponseContext/redirect.html) or [`res.serialize()`](https://www.dartdocs.org/documentation/angel_framework/latest/angel_framework/ResponseContext/serialize.html) automatically close the response.
* A `RequestHandler`: the returned handler will be executed.
* A `Stream`: `toList` will be called, and then returned.
* A `Future`: it will be awaited, and then returned.
* Anything else: Whatever other Dart value you return will be serialized as a response. The default method is to encode responses as JSON, using `json.encode`. However, you can change a response's serialization method by setting `res.serializer = foo;`. If you want to assign the same serializer to all responses, globally set [`serializer`](https://pub.dartlang.org/documentation/angel_framework/latest/angel_framework/Angel/serializer.html) on your Angel instance. If you are only returning JSON-compatible Dart objects, like Maps or Lists, you might consider injecting `JSON.encode` as a serializer, to improve runtime performance (this is the default in `2.0`).

### Other Parameters

Request handlers can take other parameters, instead of just a `RequestContext` and `ResponseContext`. Consult the [dependency injection documentation](/guides/dependency-injection.md#in-routes-and-controllers).

### Queries, Files and Bodies

You can access a mutable `Map` based on the URI query parameters by calling `RequestContext.queryParameters`.

Consult the [body parsing documentation](/guides/body-parsing.md) to understand how to handle user input.

If you [write your own plugin](https://github.com/angel-dart/gitbook/tree/0856a626a81a2baec00e419dd5496dda101bf7a6/advanced/writing-a-plugin.md), be sure to use the `lazy` alternatives.

For more information, see the API docs:

[RequestContext](https://www.dartdocs.org/documentation/angel_framework/latest/angel_framework/RequestContext-class.html)

[ResponseContext](https://www.dartdocs.org/documentation/angel_framework/latest/angel_framework/ResponseContext-class.html)

## Next Up...

Now, let's learn about Angel's [flexible router](/guides/basic-routing-1.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.angel-dart.dev/guides/requests-and-responses.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.