////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

== respond

=== Purpose

Attempts to return the most appropriate type for the requested content type (specified by either the `Accept` header or file extension)

=== Examples


[source,groovy]
----
// pick the best content type to respond with
respond Book.get(1)

// pick the best content type to respond with from the given formats
respond Book.get(1), formats: ['xml', 'json']
----


=== Description


The respond method uses link:{guidePath}theWebLayer.html#contentNegotiation[Content Negotiation] to respond with the most appropriate content type. See the documentation on  link:{guidePath}REST.html[REST support] for more information.

If a view is picked for rendering then a model will automatically be calculated to pass to the view.

The following table summarizes this convention:

[cols="3*", options="header"]
|===
|Example|Argument Type|Calculated Model Variable
|`respond Book.list()`|`java.util.List`|`bookList`
|`respond Book.get(1)` |`example.Book`|`book`
|`respond( [1,2] )` |`java.util.List`|`integerList`
|`respond( [1,2] as Set )` |`java.util.Set`|`integerSet`
|`respond( [1,2] as Integer[] )` |`Integer[]`|`integerArray`
|===

Parameters:

* `object` - The object to render
* `arguments` - Named arguments.

Supported `arguments`:

* `view` - The view to use in case of HTML rendering
* `model` - The model to use in case of HTML rendering
* `status` - The response status
* `formats` - A list of formats to respond with
* `includes` - Properties to include if rendering with the converters API
* `excludes` - Properties to exclude if rendering with the converters API

WARNING: Due to the way Groovy works, while responding with a Map and arguments it is important to respond in this manner `respond([:], status: 200)` instead of this manner `respond([:], [status: 200])`. Failure to do so will result in the arguments being reversed.

