EclipseLink Solutions Guide for EclipseLink
Release 3.0
  Go To Table Of Contents
 Search
 PDF

RESTful Data Services API Reference

The following types of RESTful operations can be used with JPA via HTTP when using RESTful Data Services:


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/{version}/{unit-name}/entity/{type}/*

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

Supported entity operations are:


FIND

HTTP Request Syntax

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

where:

Example

GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1

Produces

JSON or XML

Response


Usage

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/exampleApp/persistence/v1.0/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 REST request) is supported to one level, for example:

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

while

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


PERSIST

HTTP Request Syntax

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

Example

PUT http://localhost:8080/exampleApp/persistence/v1.0/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 idempotent. 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/{version}/{unit-name}/entity/{type}

Example

POST http://localhost:8080/exampleApp/persistence/v1.0/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/{version}/{unit-name}/entity/{type}{id}

where {id} is defined using a string

Example

DELETE http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1

Response

OK


Entity Operations on Relationships

The base URI for relationship operations is as follows:

/persistence/{version}/{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/{version}/{unit-name}/entity/{type}/{id}/{relationship}

where:

Example

GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1/myRelationship

Produces

JSON or XML

Response


ADD

Use this operation to add to a list or replace the value of a many-to-one relationship.

HTTP Request Syntax

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


NoteNote:

As of EclipseLink 2.4.2, partner should be specified as a query parameter. Specifying partner as a matrix parameter is deprecated.



Examples

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

POST http://localhost:8080/exampleApp/persistence/v1.0/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/exampleApp/persistence/v1.0/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 "Passing By Value vs. Passing By Reference".


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 a many-to-one relationship.

HTTP Request Syntax

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

where relationshipListItemId is an optional query parameter. The relationshipListItemId is meaningful only when the {relationship} to be removed is a list. The relationshipListItemId should be set to the id of a member in the relationship list when only that member of the relationship list needs to be removed. The entire list specified by the {relationship} will be removed when relationshipListItemId is not specified.

Example

DELETE http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/entity/Foo/1/myRelationship

Consumes

JSON or XML


NoteNote:

Relationship objects can be passed by value or by reference. See "Passing By Value vs. Passing By Reference".


Produces

JSON or XML

Response


Query Operations

The base URI for query operations is as follows:

GET /persistence/{version}/{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/{version}/{unit-name}/query/{name};{parameters}? {hints}

where:


Examples

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

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

Produces

JSON or XML

Response

A payload containing a list of entities. An XML response contains a List as a grouping name for a collection of items and item as a grouping name for each member of a collection returned. JSON responses use square brackets [] to encapsulate a collection and curly braces {} to encapsulate each member of a collection. For example:

XML Example

<?xml version="1.0" encoding="UTF-8"?>
<List>
   <item>
      <firstName>Miles</firstName>
      <lastName>Davis</lastName>
      <manager>
         <firstName>Charlie</firstName>
         <lastName>Parker</lastName>
         <gender>Male</gender>
         <id>26</id>
      </manager>
   </item>
   <item>
      <firstName>Charlie</firstName>
      <lastName>Parker</lastName>
      <manager>
         <firstName>Louis</firstName>
         <lastName>Armstrong</lastName>
         <gender>Male</gender>
         <id>27</id>
      </manager>
   </item>
</List>

JSON Example

[
   {
      "firstName": "Miles",
      "lastName": "Davis",
      "manager": {
         "firstName": "Charlie",
         "lastName": "Parker",
         "gender": "Male",
         "id": 26
      }
   },
   {
      "firstName": "Charlie",
      "lastName": "Parker",
      "manager": {
         "firstName": "Louis",
         "lastName": "Armstrong",
         "gender": "Male",
         "id": 27
      }
   }
]

Update/Delete Query

HTTP Request Syntax

POST /persistence/{version}/{unit-name}/query/{name};parameters?hints

where:


Examples

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

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

Produces

JSON or XML

Response

A payload containing the number of entities updated or deleted


Single Result Queries

HTTP Request Syntax

GET /persistence/{version}/{unit-name}/singleResultQuery/{name};{parameters}?{hints}

where:

Example

GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/singleResultQuery/Foo.findByName;name=myname

Produces

JSON, XML, or application/octet-stream

Response

A payload containing an entity


Base Operations

Base operations are:


List Existing Persistence Units

HTTP Request Syntax

GET /persistence/{version}

Example

GET http://localhost:8080/exampleApp/persistence/v1.0

Produces

JSON or XML

Response

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

[
   {
 
      "_link": {
         "href": "http://localhost:8080/exampleApp/persistence/v1.0/employee/metadata",
         "method": "application/json",
         "rel": "employee"
      }
   },
   {
      "_link": {
         "href": "http://localhost:8080/exampleApp/persistence/v1.0/traveler/metadata",
         "method": "application/json",
         "rel": "traveler"
      }
   }
]

Metadata Operations

The following metadata operations are supported:


List Types in a Persistence Unit

HTTP Request Syntax

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

Example

GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/metadata

Produces

JSON

Response


List Queries in a Persistence Unit

HTTP Request Syntax

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

Example

GET http://localhost:8080/exampleApp/persistence/v1.0/ExamplePU/metadata/query

Produces

JSON

Response


Describe a Specific Entity

HTTP Request Syntax

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

Example

GET http://localhost:8080/CustomerApp/persistence/v1.0/Inventory/metadata/entity/Customer

Produces

JSON

Response