579 lines
18 KiB
XML
579 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter version="5.0"
|
|
xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
|
|
xml:id="repository-resources" xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:ns="http://docbook.org/ns/docbook">
|
|
<title>Repository resources</title>
|
|
|
|
<section xml:id="repository-resources.fundamentals">
|
|
<title>Fundamentals</title>
|
|
|
|
<para>The core functionality of Spring Data REST is to export resources
|
|
for Spring Data repositories. Thus, the core artifact to look at and
|
|
potentially tweak to customize the way the exporting works is the
|
|
repository interface. Assume the following repository interface:</para>
|
|
|
|
<programlisting>public interface OrderRepository extends CrudRepository<Order, Long> { }</programlisting>
|
|
|
|
<para>For this repository, Spring Data REST exposes a collection resource
|
|
at <code>/orders</code>. The path is derived from the uncapitalized,
|
|
pluralized, simple class name of the domain class being managed. It also
|
|
exposes a an item resource for each of the items managed by te repository
|
|
under the URI template <uri>/orders/{id}</uri>. </para>
|
|
|
|
<para>By default the HTTP methods to interact with these resources map to
|
|
the according methods of <interfacename>CrudRepository</interfacename>.
|
|
Read more on that in the sections on <link
|
|
linkend="repository-resources.collection-resource">collection
|
|
resources</link> and <link
|
|
linkend="repository-resources.item-resource">item resources</link>.</para>
|
|
|
|
<section xml:id="repository-resources.default-status-codes">
|
|
<title>Default status codes</title>
|
|
|
|
<para>For the resources exposed, we use a set of default status
|
|
codes:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>200 OK</code> - for plain <code>GET</code>
|
|
requests.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>201 Created</code> - for <code>POST</code> and
|
|
<code>PUT</code> requests that create new resources.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>204 No Content</code> - for <code>PUT</code>,
|
|
<code>PATCH</code>, and <code>DELETE</code> requests if the
|
|
configuration is set to not return response bodies for resource
|
|
updates
|
|
(<code>RepositoryRestConfiguration.returnBodyOnUpdate</code>). If
|
|
the configuration value is set to include responses for
|
|
<code>PUT</code>, <code>200 OK</code> will be returned for updates,
|
|
<code>201 Created</code> will be returned for resource created
|
|
through <code>PUT</code>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="repository-resources.resource-discoverability">
|
|
<title>Resource discoverability</title>
|
|
|
|
<para>A core principle of HATEOAS is that resources should be
|
|
discoverable through the publication of links that point to the
|
|
available resources. There are a few competing de-facto standards of how
|
|
to represent links in JSON. By default, Spring Data REST uses <link
|
|
xlink:href="http://tools.ietf.org/html/draft-kelly-json-hal">HAL</link>
|
|
to render responses. HAL defines links to be contained in a
|
|
<property>_link</property> property of the returned document.</para>
|
|
|
|
<para>Resource discovery starts at the top level of the application. By
|
|
issuing a request to the root URL under which the Spring Data REST
|
|
application is deployed, the client can extract a set of links from the
|
|
returned JSON object that represent the next level of resources that are
|
|
available to the client.</para>
|
|
|
|
<para>For example, to discover what resources are available at the root
|
|
of the application, issue an HTTP <code>GET</code> to the root
|
|
URL:</para>
|
|
|
|
<programlisting>curl -v http://localhost:8080/
|
|
|
|
< HTTP/1.1 200 OK
|
|
< Content-Type: application/hal+json
|
|
|
|
{ "_links" : {
|
|
"orders" : {
|
|
"href" : "http://localhost:8080/orders"
|
|
}
|
|
}
|
|
}</programlisting>
|
|
|
|
<para>The <property>_links</property> property of the result document is
|
|
an object in itself consisting of keys representing the relation type
|
|
with nested link objects as specified in HAL.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="repository-resources.collection-resource">
|
|
<title>The collection resource</title>
|
|
|
|
<para>Spring Data REST exposes a collection resource named after the
|
|
uncapitalized, pluralized version of the domain class the exported
|
|
repository is handling. Both the name of the resource and the path can be
|
|
customized using the
|
|
<interfacename>@RepositoryRestResource</interfacename> on the repository
|
|
interface.</para>
|
|
|
|
<section>
|
|
<title>Supported HTTP Methods</title>
|
|
|
|
<para>Collections resources support both <code>GET</code> and
|
|
<code>POST</code>. All other HTTP methods will cause a <code>405 Method
|
|
Not Allowed</code>.</para>
|
|
|
|
<section>
|
|
<title><code>GET</code></title>
|
|
|
|
<para>Returns all entities the repository servers through its
|
|
<methodname>findAll(…)</methodname> method. If the repository is a
|
|
paging repository we include the pagination links if necessary and
|
|
additional page metadata.</para>
|
|
|
|
<simplesect>
|
|
<title>Parameters</title>
|
|
|
|
<para>If the repository has pagination capabilities the resource
|
|
takes the following parameters:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>page</code> - the page number to access (0 indexed,
|
|
defaults to 0).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>size</code> - the page size requested (defaults to
|
|
20).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>sort</code> - a collection of sort directives in the
|
|
format <code>($propertyname,)+[asc|desc]</code>?.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>405 Method Not Allowed</code> - if the
|
|
<methodname>findAll(…)</methodname> methods was not exported
|
|
(through <code>@RestResource(exported = false)</code>) or is not
|
|
present in the repository at all.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Related resources</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>search</code> - a <link
|
|
linkend="repository-resources.search-resource">search
|
|
resource</link> if the backing repository exposes query
|
|
methods.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
|
|
<section>
|
|
<title><code>POST</code></title>
|
|
|
|
<para>Creates a new entity from the given request body.</para>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>405 Method Not Allowed</code> - if the
|
|
<methodname>save(…)</methodname> methods was not exported
|
|
(through <code>@RestResource(exported = false)</code>) or is not
|
|
present in the repository at all.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="repository-resources.item-resource">
|
|
<title>The item resource</title>
|
|
|
|
<para>Spring Data REST exposes a resource for individual collection items
|
|
as sub-resources of the collection resource.</para>
|
|
|
|
<section>
|
|
<title>Supported HTTP methods</title>
|
|
|
|
<para>Item resources generally support <code>GET</code>,
|
|
<code>PUT</code>, <code>PATCH</code> and <code>DELETE</code> unless
|
|
explicit configuration prevents that (see below for details).</para>
|
|
|
|
<section>
|
|
<title><code>GET</code></title>
|
|
|
|
<para>Returns a single entity.</para>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>405 Method Not Allowed</code> - if the
|
|
<methodname>findOne(…)</methodname> methods was not exported
|
|
(through <code>@RestResource(exported = false)</code>) or is not
|
|
present in the repository at all.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Related resources</title>
|
|
|
|
<para>For every association of the domain type we expose links named
|
|
after the association property. This can be customized by using
|
|
<interfacename>@RestResource</interfacename> on the property. The
|
|
related resources are of type <link
|
|
linkend="repository-resources.association-resource">association
|
|
resource</link>.</para>
|
|
</simplesect>
|
|
</section>
|
|
|
|
<section>
|
|
<title><code>PUT</code></title>
|
|
|
|
<para>Replaces the state of the target resource with the supplied
|
|
request body.</para>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>405 Method Not Allowed</code> - if the
|
|
<methodname>save(…)</methodname> methods was not exported
|
|
(through <code>@RestResource(exported = false)</code>) or is not
|
|
present in the repository at all.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
|
|
<section>
|
|
<title><code>PATCH</code></title>
|
|
|
|
<para>Similar to <code>PUT</code> but only applying values sent with
|
|
the request body.</para>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>405 Method Not Allowed</code> - if the
|
|
<methodname>save(…)</methodname> methods was not exported
|
|
(through <code>@RestResource(exported = false)</code>) or is not
|
|
present in the repository at all.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
|
|
<section>
|
|
<title><code>DELETE</code></title>
|
|
|
|
<para>Deletes the resource exposed.</para>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>405 Method Not Allowed</code> - if the
|
|
<methodname>delete(…)</methodname> methods was not exported
|
|
(through <code>@RestResource(exported = false)</code>) or is not
|
|
present in the repository at all.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="repository-resources.association-resource">
|
|
<title>The association resource</title>
|
|
|
|
<para>Spring Data REST exposes sub-resources of every item resource for
|
|
each of the associations the item resource has. The name and path of the
|
|
of the resource defaults to the name of the association property and can
|
|
be customized using <interfacename>@RestResource</interfacename> on the
|
|
association property. </para>
|
|
|
|
<section>
|
|
<title>Supported HTTP methods</title>
|
|
|
|
<section>
|
|
<title>GET</title>
|
|
|
|
<para>Reutrns the state of the association resource</para>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
|
|
<section>
|
|
<title>PUT</title>
|
|
|
|
<para>Binds the resource pointed to by the given URI(s) to the
|
|
resource. This </para>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>400 Bad Request</code> - if multiple URIs were given
|
|
for a to-one-association.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>text/uri-list - URIs pointing to the resource to bind to
|
|
the association.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
|
|
<section>
|
|
<title>POST</title>
|
|
|
|
<para>Only supported for collection associations. Adds a new element
|
|
to the collection.</para>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>text/uri-list - URIs pointing to the resource to add to
|
|
the association.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
|
|
<section>
|
|
<title>DELETE</title>
|
|
|
|
<para>Unbinds the association.</para>
|
|
|
|
<simplesect>
|
|
<title>Custom status codes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>405 Method Not Allowed</code> - if the association
|
|
is non-optional.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="repository-resources.search-resource">
|
|
<title>The search resource</title>
|
|
|
|
<para>The search resource returns links for all query methods exposed by a
|
|
repository. The path and name of the query method resources can be
|
|
modified using <interfacename>@RestResource</interfacename> on the method
|
|
declaration.</para>
|
|
|
|
<section>
|
|
<title>Supported HTTP methods</title>
|
|
|
|
<para>As the search resource is a read-only resource it supports
|
|
<code>GET</code> only.</para>
|
|
|
|
<section>
|
|
<title><code>GET</code></title>
|
|
|
|
<para>Returns a list of links pointing to the individual query method
|
|
resources</para>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Related resources</title>
|
|
|
|
<para>For every query method declared in the repository we expose a
|
|
<link linkend="repository-resources.query-method-resource">query
|
|
method resource</link>. If the resource supports pagination, the URI
|
|
pointing to it will be a URI template containing the pagination
|
|
parameters.</para>
|
|
</simplesect>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="repository-resources.query-method-resource">
|
|
<title>The query method resource</title>
|
|
|
|
<para>The query method resource executes the query exposed through an
|
|
individual query method on the repository interface.</para>
|
|
|
|
<section>
|
|
<title>Supported HTTP methods</title>
|
|
|
|
<para>As the search resource is a read-only resource it supports
|
|
<code>GET</code> only.</para>
|
|
|
|
<section>
|
|
<title><code>GET</code></title>
|
|
|
|
<para>Returns the result of the query execution.</para>
|
|
|
|
<simplesect>
|
|
<title>Parameters</title>
|
|
|
|
<para>If the query method has pagination capabilities (indicated in
|
|
the URI template pointing to the resource) the resource takes the
|
|
following parameters:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>page</code> - the page number to access (0 indexed,
|
|
defaults to 0).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>size</code> - the page size requested (defaults to
|
|
20).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>sort</code> - a collection of sort directives in the
|
|
format <code>($propertyname,)+[asc|desc]</code>?.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
|
|
<simplesect>
|
|
<title>Supported media types</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>application/hal+json</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>application/json</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</chapter>
|