Loading
EclipseLink Solutions Guide for EclipseLink
Release 2.5
  Go To Table Of Contents
Contents
 Search
Other Searches
 PDF
PDF
Comments
Comments

Beta Draft: 2013-04-04

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 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

HTTP Request Syntax

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

where:

Example

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

Produces

JSON or XML

Response


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

Use this operation to get the values of a relationship.

HTTP Request Syntax

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

where:

Example

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

Produces

JSON or XML

Response


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.


NoteNote:

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


NoteNote:

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


Produces

JSON or XML

Response


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

HTTP Request Syntax

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

where:


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:


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:

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

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:


NoteNote:

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

Response


Metadata Operations

The following metadata operations are supported:


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


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


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

Comments powered by Disqus