Database resources

Introduction

Kauri's database resources (often called DB resources) provide an easy way to expose database entities as RESTful resources.

Two implementations are provided:

• One that works on top of JPA (Java Persistence API, implemented by Hibernate and others)
• One that allows to mock database resources by creating JSON files on the filesystem. This is useful at early stages in the project, when the real database resources are not yet available. It can also be useful at later stages in the project, to experiment with new entities or to work on the front-end without access to the database.

Interface

Here we describe the interface which is common to all database resource implementations.

URI structure

The URI structure can be summarized as follows (* = 0 or more occurences, ? = 0 or 1 occurence):

/entityname(/id/propertyname)*(/id)?

The following table shows some examples of what is possible:

/myentity	list of all myentity records
/myentity/1	the entity myentity with id = 1
/myentity/1/myproperty	assuming myproperty is a property of myentity, and that myproperty is an entity by itself, this will return the entity associated through myproperty. If myproperty is a list, it will return the list of all such entities.
/myentity>/1/myproperty/2	Same as the previous, but assumes myproperty is a list, and will only return the entity with id = 2.

Methods

The HTTP methods have their usual meaning. GET, PUT, POST, DELETE, HEAD and OPTIONS are all supported

Creating a new entity is done by posting to a list-URI. So the ID of the new entity is assigned by the server.

Querying

Querying (searching) for entities is done using the query string on list-URIs.

The name of the property to search on should be preceded by "q.".

Searching on a single property:
/myentity?q.propertyname=value

Searching on multiple properties:
/myentity?q.propertyname1=value1&q.propertyname2=value2

Sorting

When lists of entities are returned, you can specify sorting options to influence the order.

The parameters are:

sort.{seqnr}=propertyname
order.{seqnr}=asc|desc

where seqnr is 1, 2, ...

Specifying the order is optional, default is ascending.

Example:

?sort.1=prop1&order.1=desc&sort.2=prop2

Paging

When lists of entities are returned, you can use paging options to avoid that the complete list is returned.

The paging options are specified using the following request parameters:

page	The page number, the first page is numbered 1. If the page number is larger than the number of available pages, an empty result will be returned.
pageSize	(optional) The size of a page, default is 10.

When the page request parameter is present, the plain list result will be wrapped in a container describing the page.

For example, for the JSON format, this container is as follows:

{
  page: 1,
  pageSize: 10,
  totalPages: 5,
  totalRows: 46,
  data: [ { ... }, { ... }, ...]
}