HTTP Request Reference for JPA-RS

The following types of RESTful operations can be used with JPA via HTTP when using JPA-RS.

Entity Operations
Entity Operations on Relationships
Query Operations
Base Operations
Metadata Operations

Entity Operations

Entity operations are those performed against a specific entity type within the persistence unit.

The base URI for entity operations is as follows:

/persistence/{unit-name}/entity/{type}/*

The {type} value refers to the type name (descriptor alias).

Supported entity operations are:

FIND
PERSIST
MERGE
DELETE

FIND

HTTP Request Syntax

GET /persistence/{unit-name}/entity/{type}/{id} hints

where:

{id} is a string
hints are specified using HTTP query parameters, with the key being the name of the EclipseLink query hint

Example

GET http://localhost:8080/persistence/ExamplePU/entity/Foo/1

Produces

JSON or XML

Response

OK, with a payload containing the entity
NOT_FOUND if the entity does not exist

Usage

The EntityManager.find API is as follows:

public <T> T find(Class<T> entityClass, Object primaryKey);
public <T> T find(Class<T> entityClass, Object primaryKey, Map<String, Object> properties);

Hints specified in the request are put into the properties. For example, see below.

Composite Keys

Composite keys are supported. The + character is reserved and therefore cannot be used in fields that represent keys. Composite keys are separated using the + character and should be specified in an order corresponding to the Java default sorting of the attribute names.

For example, consider an entity Phone, with attributes extB=123 and extA=321. The URL to find the entity is:

http://localhost:8080/persistence/ExamplePU/entity/Phone/321+123

The 321 comes before the 123 because extA comes before extB when sorted in Java.

Result Caching

Default EclipseLink and HTTP caching is enabled and configured through standard means.

Refresh

The EntityManager.refresh operation can be invoked using the find with the query hint for Refresh.

Attributes

Navigating into the attributes of an entity (for example, to get the Address entity associated with an employee in a single URL) is supported to one level, for example:

/persistence/{unit-name}/entity/{type}/{id}/{relationship} will work

while

/persistence/{unit-name}/entity/{type}/{id}/{relationship}/{index}/{relationship2} will not

PERSIST

HTTP Request Syntax

PUT /persistence/{unit-name}/entity/{type}

Example

PUT http://localhost:8080/persistence/ExamplePU/entity/Foo

Consumes

JSON or XML

Payload

Entity

Produces

JSON or XML

Response

Payload containing the entity returned by the persist operation

Usage

PUT is required to be itempotent. As a result, it will fail if called with an object that expects the server to provide an ID field. Typically this will occur if the metadata specifies a generated key and the field that contains that key is unpopulated.

MERGE

HTTP Request Syntax

POST /persistence/{unit-name}/entity/{type}

Example

POST http://localhost:8080/persistence/ExamplePU/entity/Foo

Consumes

JSON or XML

Payload

Entity

Produces

JSON or XML

Response

Payload containing the entity returned by the merge operation.

Merge takes an object graph and makes it part of the persistence context through comparison. It compares the object and all related objects to the ones that already exist and issues INSERTs, UPDATEs, and DELETEs to put the object in the persistence context.

DELETE

HTTP Request Syntax

DELETE /persistence/{unit-name}/entity/{type}{id}

where {id} is defined using HTTP query parameters

Example

DELETE http://localhost:8080/persistence/ExamplePU/entity/Foo?id=1

Response

OK

Entity Operations on Relationships

The base URI for relationship operations is as follows:

/persistence/{unit-name}/entity/{entity}/{id}/{relationship}

Supported relationship operations are:

READ
ADD
REMOVE

READ

Use this operation to get the values of a relationship.

HTTP Request Syntax

GET /persistence/{unit-name}/entity/{type}/{id}/{relationship}

where:

{id} is a string.
{relationship} is the JPA name of the relationship.

Example

GET http://localhost:8080/persistence/ExamplePU/entity/Foo/1/myRelationship

Produces

JSON or XML

Response

OK, Payload containing an entity or a list of entities.
NOT_FOUND if the entity does not exist

ADD

Use this operation to add to a list or replace the value of an x-1 relationship.

HTTP Request Syntax

POST /persistence/{unit-name}/entity/{type}/{id}/{relationship}{partner}

Examples

For unidirectional relationships, {partner} is not required, for example:

POST http://localhost:8080/persistence/ExamplePU/entity/Foo/1/myRelationship

For bi-directional relationships, you must provide the name of the attribute that makes up the opposite side of the relationship. For example, to update an Auction.bid where the opposite side of the relationship is Bid.auction, use the following:

POST http://localhost:8080/persistence/ExamplePU/entity/Foo/1/myRelationship;partner=bid

Consumes

JSON or XML

Payload

Entity with the new value.

Note:

Relationship objects can be passed by value or by reference. See "Pass By Reference, Pass By Value".

Produces

JSON or XML

Response

Payload containing the entity with the added element

REMOVE

Use this operation to remove a specific entity from the list or a null on an x-1 relationship.

HTTP Request Syntax

DELETE /persistence/{unit-name}/entity/{type}/{id}/{relationship}

Example

DELETE http://localhost:8080/persistence/ExamplePU/entity/Foo/1/myRelationship

Consumes

JSON or XML

Payload

The entity to be removed

Note:

Relationship objects can be passed by value or by reference. See "Pass By Reference, Pass By Value".

Produces

JSON or XML

Response

OK
Payload containing the entity with the removed element

Query Operations

The base URI for query operations is as follows:

GET /persistence/{unit-name}/query/{name}{params}

The following query operations are supported:

Named queries doing reads can be run two ways in JPA. Both are supported in the REST API. They are:

Query Returning List of Results
Update/Delete Query

Query Returning List of Results

HTTP Request Syntax

GET /persistence/{unit-name}/query/{name} parameters hints

where:

parameters are specified using HTTP matrix parameters
hints are specified using HTTP query parameters and with the key being the name of the EclipseLink query hint

Examples

GET http://localhost:8080/persistence/ExamplePU/query/Foo.findByName;name=myname

GET http://localhost:8080/persistence/ExamplePU/query/Foo.findByName;name=myname?eclipselink.jdbc.max-results=500

Produces

JSON or XML

Response

A payload containing a list of entities.

Update/Delete Query

HTTP Request Syntax

POST /persistence/{unit-name}/query/{name} parameters hints

where:

parameters are specified using HTTP matrix parameters
hints are specified using HTTP query parameters and with the key being the name of the EclipseLink query hint

Examples

POST http://localhost:8080/persistence/ExamplePU/query/Foo.deleteAllByName;name=myname

POST http://localhost:8080/persistence/ExamplePU/query/Foo.updateName;name=myname?eclipselink.jdbc.max-results=500

Produces

application/octet-stream

Response

A payload containing the number of entities updated or deleted

Single Result Queries

HTTP Request Syntax

GET /persistence/{unit-name}/querySingleResult/{name} parameters hints

where:

parameters are specified using HTTP matrix parameters
hints are specified using HTTP query parameters and with the key being the name of the EclipseLink query hint

Example

GET http://localhost:8080/persistence/ExamplePU/querySingleResult/Foo.findByName;name=myname

Produces

JSON or XML

Response

A payload containing an entity

Base Operations

Base operations are:

List Existing Persistence Units
Call a Session Bean

List Existing Persistence Units

HTTP Request Syntax

GET /persistence

Example

GET http://localhost:8080/persistence/

Produces

JSON

Response

A payload containing a list of persistence unit names and links to metadata about them. For example,

[
  {
    "rel": "auction",
    "type": "application/json",
    "href": "http://localhost:8080/Model/jpa-rs/auction/metadata"
  },
  {
    "rel": "DataAppLibraryPU",
    "type": "application/json",
    "href": "http://localhost:8080/Model/jpa-rs/DataAppLibraryPU/metadata"
  }
]

Call a Session Bean

HTTP Request Syntax

POST /persistence

where the payload is a SessionBeanCall JSON or XML object containing the following information:

jndiName - The JNDI name of the SessionBean
methodName - The name of the SessionBean method to call
context - (optional) The JPA RS context to use to unmarshall parameters and marshall return values. If not provided, return values are returned as is
parameters - A list of parameter Object with the following information
- typeName - The name of the java class of the parameter, or the name of the entity type in JPA RS
- value - The value of the parameter

Note:

To support the security of an application, it is recommended that you disable this URL pattern by default. Only enable specific patterns that allow calling beans that are designed to be called.

Produces

Produces */* for entities in XML or JSON
For queries that return single fields, returns the type associated with the field

Response

NOT_FOUND if the context is not found or the session bean cannot be found on lookup
OK when successful, with a payload containing the return value of a SessionBean method

Metadata Operations

The following metadata operations are supported:

List Types in a Persistence Unit
List Queries in a Persistence Unit
Describe a Specific Entity

List Types in a Persistence Unit

HTTP Request Syntax

GET /persistence/{unit-name}/metadata

Example

GET http://localhost:8080/persistence/ExamplePU/metadata

Produces

JSON

Response

OK, with a payload containing a list of types, with links to more detailed metadata

for example,

{
  "persistence-unit-name": "auction",
  "types": [
    {
      "rel": "User",
      "type": "application/json",
      "href": "http://localhost:8080/Model/jpa-rs/auction/metadata/entity/User"
    },
    {
      "rel": "Auction",
      "type": "application/json",
      "href": "http://localhost:8080/Model/jpa-rs/auction/metadata/entity/Auction"
    },
    {
      "rel": "Bid",
      "type": "application/json",
      "href": "http://localhost:8080/Model/jpa-rs/auction/metadata/entity/Bid"
    }
  ]
}

NOT_FOUND if the persistence unit is not found

List Queries in a Persistence Unit

HTTP Request Syntax

GET /persistence/{unit-name}/metadata/query

Example

GET http://localhost:8080/persistence/ExamplePU/metadata/query

Produces

JSON

Response

OK with a payload containing a list of all available queries, for example,

[
  {
    "query-name": "User.all",
    "reference-type": "jpars.app.auction.model.User",
    "jpql": "SELECT u from User u",
    "link-template": {
      "rel": "execute",
      "method": "get",
      "href": "http://localhost:8080/Model/jpa-rs/auction/query/User.all/{parameters}"
    }
  },
  {
    "query-name": "User.updateName",
    "reference-type": "jpars.app.auction.model.User",
    "jpql": "UPDATE User u SET u.name = :name WHERE u.id = :id",
    "link-template": {
      "rel": "execute",
      "method": "post",
      "href": "http://localhost:8080/Model/jpa-rs/auction/query/User.updateName/{parameters}"
    }
  }
]

NOT_FOUND if persistence unit is not found

Describe a Specific Entity

HTTP Request Syntax

GET /persistence/{unit-name}/metadata/entity/ type

Example

GET http://localhost:8080/persistence/ExamplePU/metadata/entity/MyEntity

Produces

JSON

Response

OK, with a payload containing details about the entity and available operations on it, for example,

{
  "name": "User",
  "type": "jpars.app.auction.model.User",
  "link-templates": [
    {
      "rel": "find",
      "type": "application/json",
      "method": "get",
      "href": "http://localhost:8080/Model/jpa-rs/auction/entity/Bid/{primaryKey}"
    },
    {
      "rel": "persist",
      "type": "application/json",
      "method": "put",
      "href": "http://localhost:8080/Model/jpa-rs/auction/entity/Bid"
    },
    {
      "rel": "update",
      "type": "application/json",
      "method": "post",
      "href": "http://localhost:8080/Model/jpa-rs/auction/entity/Bid"
    },
    {
      "rel": "delete",
      "type": "application/json",
      "method": "delete",
      "href": "http://localhost:8080/Model/jpa-rs/auction/entity/Bid/{primaryKey}"
    }
  ],
  "attributes": [
    {
      "name": "id",
      "type": "java.lang.Integer"
    },
    {
      "name": "name",
      "type": "java.lang.String"
    }
  ],
  "queries": [
    {
      "query-name": "User.all",
      "reference-type": "jpars.app.auction.model.User",
      "jpql": "SELECT u from User u"
    },
    {
      "query-name": "User.updateName",
      "reference-type": "jpars.app.auction.model.User",
      "jpql": "UPDATE User u SET u.name = :name WHERE u.id = :id"
    }
  ]
}

NOT_FOUND if the persistence unit is not found