Skip to main content
Jump to: navigation, search

Difference between revisions of "EclipseLink/Development/2.4.0/JPA-RS/REST-API"

 
(116 intermediate revisions by 3 users not shown)
Line 1: Line 1:
__NOTOC__
+
[http://www.eclipse.org/eclipselink/documentation/2.4/solutions/restful_jpa003.htm#CHDEGJIG JPA-RS API Documentation version 2.4.0]
= JAX-RS: A RESTful API for JPA=
+
 
+
'''History'''
+
Date
+
Author
+
Description
+
01/10/11
+
dclarke
+
Initial Version
+
 
+
{|{{BMTableStyle}}
+
|-{{BMTHStyle}}
+
! Date
+
! Author
+
! Description
+
|-
+
| Oct 1, 2011 || dclarke || Initial Version
+
|-
+
| Nov 9, 2011 || dclarke || Moved to wiki for community review and feedback.
+
|}
+
 
+
==Overview==
+
 
+
This specification will define a RESTful API for dealing with JPA. The intent is to simplify how JPA persistence units can be accessed using REST with JSON or XML formatted messages. A JPA-RS runtime will provide access to all persistence units packaged in the same application that it is running in as well as any dynamic persistence unit that is provisioned within it.
+
 
+
===URI Root : /persistence===
+
The root URI for the RESTful interface is defined in the application's web.xml:
+
  <servlet-mapping>
+
    <servlet-name>Jersey REST Service</servlet-name>
+
    <url-pattern>/persistence/*</url-pattern>
+
  </servlet-mapping>
+
 
+
Here the root URI is 'persistence' to differentiate it from other services
+
 
+
== Persistence Unit Operations==
+
 
+
The JPA-RS URI structure is then requires a persistence unit name: '''/persistence/{unit-name}'''. Assuming this is a valid persistence unit in the give JPA-RS application context the following high level operations are available.
+
 
+
* ENTITY: /persistence/{unit-name}/entity
+
* QUERY: /persistence/{unit-name}/query
+
* METAMODEL: /persistence/{unit-name}/metamodel
+
* ADMIN: /persistence/{unit-name}
+
 
+
=== HTTP Method Basics ===
+
 
+
The HTTP methods used in JPA-RS with there basic interpretation in persistence are:
+
 
+
* GET:
+
* PUT: enclosed entity be stored under the supplied Request-URI
+
** INSERT when the PK entity does not exist
+
** UPDATE when the entity does exist
+
* POST: new subordinate of resource identified by the request-URI
+
* DELETE:
+
 
+
The HEAD, TRACE, and CONNECT methods currently have no defined meaning in JPA-RS
+
 
+
===Data Formats: JSON or XML===
+
This REST interface deals with XML and JSON representations of the data equally well. The caller is responsible for using the HTTP header values to indicate the format of the content it is sending (Content-Type = application/json or application/xml) as well as indicating the format of the result it expects (Accept = application/json or application/xml).
+
In cases where no header value is specified JSON will be used by default and in cases where content-type is specified and accept is not the returned format will match the content-type passed in.
+
NOTE: In many REST utilities the accept value is defaulted to application/xml making it the users responsibility to configure this value explicitly.
+
 
+
 
+
===Web Caching===
+
In addition to the internal caching within TopLink (EclipseLink) the results from REST URI calls can be cached in various points between the initiating server and the user, including their browser. This caching is determined by URI structure and the HTTP header information in the response from the REST calls. Generally only GET call responses are cached so these must be addressed carefully to ensure the proper caching information is provided so that the end user of the RESTful persistence interface get the most correct information possible while still benefiting from web caching.
+
TODO: Add guidelines
+
 
+
===HTTP Header Fields ===
+
 
+
'''Standard HTTP'''
+
* If-Match - conditional
+
* Warning
+
 
+
'''EclipseLink JPA-RS'''
+
* Refresh
+
 
+
== Entity Operations: /persistence/{unit-name}/entity/* ==
+
 
+
Entity operations are those performed against a specific entity type within the persistence unit. The {type} value refers to the type name (descriptor alias).
+
 
+
=== FIND ===
+
 
+
* GET /persistence/{unit-name}/entity/{type}{id}
+
** Refresh = GET + Header(Refresh)
+
** {id} is currently defined using HTTP query parameters (we will likely change this)
+
** e.g. http://localhost:8080/persistence/ExamplePU/entity/Foo?id=1
+
* Produces: JSON or XML
+
* Response
+
** OK, Payload: Entity
+
** NOT_FOUND if Entity does not exist
+
 
+
'''EntityManager.find API:'''
+
<pre>
+
public <T> T find(Class<T> entityClass, Object primaryKey);
+
public <T> T find(Class<T> entityClass, Object primaryKey, Map<String, Object> properties);
+
</pre>
+
 
+
The JPA-RS GET with format
+
 
+
==== Composite Key ====
+
 
+
=== Result Caching ===
+
 
+
==== REFRESH ====
+
 
+
The EntityManager.refresh operation can be invoked using the find (GET) with the addition of the '''Refresh''' header field.
+
 
+
=== PERSIST ===
+
 
+
* PUT /persistence/{unit-name}/entity/{type}
+
** e.g. PUThttp://localhost:8080/persistence/ExamplePU/entity/Foo
+
* Consumes: JSON or XML
+
* Payload: Entity
+
* Produces: JSON or XML
+
* Response:
+
** Payload: Entity returned by Persist
+
 
+
=== MERGE ===
+
 
+
* POST /persistence/{unit-name}/entity/{type}
+
** e.g. POST http://localhost:8080/persistence/ExamplePU/entity/Foo
+
* Consumes: JSON or XML
+
* Payload: Entity
+
* Produces: JSON or XML
+
* Response:
+
** Payload: Entity returned by Merge
+
 
+
=== DELETE ===
+
 
+
// TODO
+
+
* DELETE /persistence/{unit-name}/entity/{type}{id}
+
* DELETE /persistence/{unit-name}/entity
+
 
+
 
+
== Query Operations ==
+
 
+
* Named Query: GET /persistence/{unit-name}/query/{name}{params}
+
* Dynamic Query: GET /persistence/{unit-name}/query
+
** Dynamic JPQL query in payload
+
** Dynamic native query in payload
+
 
+
=== Named Query ===
+
TODO
+
 
+
=== Dynamic Query ===
+
TODO
+
 
+
== Metamodel Operations ==
+
 
+
* GET /persistence/{unit-name}/metamodel
+
* GET /persistence/{unit-name}/metamodel/entity/{type}
+
* GET /persistence/{unit-name}/metamodel/query/{name}
+
 
+
== Admin Operations ==
+
 
+
The admin operations, which can be disabled in a given deployment, focus on persistence unit level administration operations:
+
 
+
* Create
+
** Dynamic Persistence Unit: PUT: /persistence/{unit-name}
+
** Add Dynamic Type: POST: /persistence/{unit-name}/
+
* Delete Persistence Unit: DELETE /persistence/{unit-name}
+
 
+
=== Create Dynamic Persistence Unit ===
+
 
+
Creating a dynamic persistence unit within a JPA-RS runtime involves passing in the necessary EclipseLink metadata and having the PU realized using dynamic entities.
+

Latest revision as of 10:22, 9 April 2013

JPA-RS API Documentation version 2.4.0

Copyright © Eclipse Foundation, Inc. All Rights Reserved.