Jello framework

Introduction

Jello provides a very powerful and comprehensive RESTful implementation that follows the OData specification. OData (Open Data Protocol) helps you focus on your business logic while building RESTful APIs without having to worry about the different approaches to fetch and interact with the data.

With Jello REST, you get complete support for all CRUD (Create, Retrieve, Update, Delete) operations and can construct complex queries to manipulate the data retrieval structure.

Jello offers a clean, and simple to follow, JSON format. Its protocol schema follows the OData v2 specification.

This document is not intend to cover all OData protocol details.
* For complete reference of the OData protocol, please refer to OData official documentation.


URI Components

OData Uri

The following is an example URI broken down into its component parts:

http://jello-framework.com/jello/data/app.catalog/Category(1)/products?$top=2&$orderby=name
________________________________/___/ _______________________________/____________________/
                |                 |          	|                    	      |
         service root URI       aspect       resource path               query options			

- Request Aspect

- Resource path

- CRUD operations

- Query options

- Other API options


- data

data request aspect is used to perform all CRUD operations and to invoke actions.

Example: /jello/data/demo/Product


- meta

meta request aspect is used to get an entity's metadata.

Example: /jello/meta/demo/Product


- view

Jello offers a unique out-of-the-box data views feature in addition to the OData protocol. By simply replacing the protocol /jello/data/ prefix with /jello/view/ you will get UI views so you can test your application and start to interact with the data instantly.

Example: /jello/view/demo/Product


Consider the following Entity definition:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
package app.demo;

@View(name="newest", top=10, orderBy="yearModel")
public class Car extends JelloEntity {
	
   @Expose @KeyElement
   public String licensePlate;
	
   @Expose @KeyElement
   public String registeredAtState;
	
   @Expose
   public Integer yearModel;
	
   @Expose @NotPersistent @Association(mappedBy="car")
   private List<Driver>drivers;

   @Accessible
   public void beep() {...}
}

Namespace resource request:
../jello/<aspect>/app.demo

Entity resource request:
../jello/<aspect>/app.demo/Car

Entity's records count request:
../jello/data/app.demo/Car/$count

Entity's view resource request:
- check @View annotation section for more details
../jello/<aspect>/app.demo/Car::newest

Instance resource request:
../jello/<aspect>/app.demo/Car(1234-CA)

Element resource request:
../jello/data/app.demo/Car(1234-CA)/yearModel

Association element resource request:
../jello/data/app.demo/Car(1234-CA)/drivers[0]

Element value resource request:
../jello/data/app.demo/Car(1234-CA)/yearModel/$value

Action invocation request:
- check Calling action via REST API for more details
../jello/data/app.demo/Car(1234-CA)/beep()

Retrieve record:
GET: ../jello/datat/app.demo/Car(1234-CA)
retrive record list response

* Learn more about deferred content here


Create record:
POST: ../jello/datat/app.demo/Car
POST body preload: {"licensePlate" : "1234-AB", "registeredAtState" : "CA", "yearModel", 2013}

Update (overwrite) record:
PUT: ../jello/datat/app.demo/Car(1234-AB-CA)
PUT body preload: {"licensePlate" : "1234-AB", "registeredAtState" : "CA", "yearModel", 2000}

Patch (partial update) record:
POST: ../jello/datat/app.demo/Car(1234-AB-CA)
request header: "X-HTTP-Method" = "MERGE"
POST body preload: {"CA", "yearModel", 2000}

Delete record:
DELETE: ../jello/datat/app.demo/Car(1234-AB-CA)

Batch delete:

DELETE: ../jello/datat/app.demo/Car(1234-AB-CA,555-NY,666-NV)

Delete by query:

DELETE: ../jello/datat/app.demo/Car?$filter=yearModel eq 2001

All Jello request options are passed as URl parameters and prefixed with a '$' sign. You can include other custom parameters in the request URL as long as they do not start with '$'.

Syntax:

/...?$param-1=value1&param-2=value-2&...&param-N=value-N

  • $filter

  • Specifies a filter to apply to the REST query.

    Jello implementation for GAE uses the Java JDO Query engine to execute the queries. The filter syntax (called JDOQL) is similar to SQL. For performance reasons, there are some restrictions on the filter expression. For more details, refer to the Queries with JDOQL full documentation. For OData compatibility, both JDOQL and OData operators can be used.

    Operator (JDOQL syntax) Operator (OData equivalent) Meaning
    == eq Equal to
    < lt Less than
    <= le Less than or equal to
    > gt Greater than
    >= ge Greater than or equal to
    != ne Not equal to
    || OR Logical "or"
    && AND Logical "and"

    The filter syntax support literals as demonstrated in the following table:

    Type Literal syntax example
    String $filter=category == 'Electronics'
    Numeric (Integer) $filter=price < 200
    Numeric (floating point) $filter=price < 200.0
    Date $filter=createdOn < \DATE(milliseconds)\ (coming soon)
    Reference $filter=producer == KEY:demo.Producer(P-2)


    Examples:

    /jello/data/demo/Product?$filter=price>20.0

    /jello/data/demo/Product?$filter=price>20.0 and price<40.0

    /jello/data/demo/Product?$filter=name == "P_2"

    /jello/data/demo/Product?$filter=name != "P_2"

    /jello/data/demo/Product?$filter=category == null

    /jello/data/demo/Product?$filter=description != null

    /jello/data/demo/Product?$filter=category == KEY:demo.Category(5) or category == KEY:demo.Category(6)



  • $search

  • Free textual search across all entity fields.
    By default, Jello will make a best effort to index all the fields for a given entity. (See @Searchable for more details.)

    If $inlinecount is specified, __matchedCount entry will be added to the response showing the number of matched results.

    Examples:

    /jello/data/demo/Product?$inlinecount=allpages&$search=TV



  • $orderby

  • Specifies which field(s) to sort the result-set by. $orderby sorts the records in ascending order by default. To sort the records in a descending order, you can use the DESC keyword.

    Syntax:

    $orderby=field1[ ASC|DESC][,field2 [ ASC|DESC],...,fieldN [ ASC|DESC]]

    Examples:

    /jello/data/demo/Product?$orderby=price

    /jello/data/demo/Product?$orderby=price DESC

    /jello/data/demo/Product?$orderby=price DESC, name ASC



  • $audit

  • Use this option to include Audit fields in the response. Audit fields are not included in the REST response by default (see Audit fields for more details).

    Example: /jello/data/demo/Category?$audit=true



  • $expand

  • To conserve resources (bandwidth, CPU, DB calls, and so on), Jello will defer sending Reference and Associations entries unless the client explicitly asks for them using the $expand option.

    Syntax:

    $expand=*|field-1[(id)],[ field-2[(id)],...,field-N[(id)]][/*|field-1[(id)],[ field-2[(id)],...,field-N[(id)]]]

    The syntax of an $expand query option is a comma-separated list of deferred elements. Additionally each level can be followed by a forward slash and another list of deferred elements to enable identifying a multi-level relationship.

    It is also possible to narrow the expanded expression only to a specific path along the entities hierarchy by specifying an instance ID. This can be very useful when you need to expand an entity's tree to retrieve a specific child. (See also Hierarchy relationship) TODO: ..........

    Examples:

    /jello/data/showbiz/Movie?$expand=*

    /jello/data/showbiz/Movie?$expand=cast

    /jello/data/showbiz/Movie?$expand=cast(Gone with the Wind)

    /jello/data/showbiz/Movie?$expand=*/*

    /jello/data/showbiz/Movie?$expand=*/star/photo

    /jello/data/showbiz/Movie?$expand=cast,producer/*/photo



  • $select

  • By default, the response will include all accessible fields. Use this option to specify which fields to include in the response.

    Syntax:

    $select=[ONE] field-1,[ field-2,...,field-N]

    Examples:

    /jello/data/demo/Product?$select=description,price

    /jello/data/demo/Product?$select=description as key,price as value

    /jello/data/demo/Product?$select=ONE description,price



  • $top

  • Specify how many records to retrieve.

    Example: /jello/data/app/Car?$top=3


  • $skip

  • Specify the number of results to skip before returning the first on.

    Examples:

    /jello/data/app/Car?$skip=2

    /jello/data/app/Car?$skip=2&$top=3



  • $cursor

  • Query cursors allow an application to retrieve a query's result in convenient batches without incurring the overhead of a query offset. For any subset query, a __next entry will be added to the result set, specify the URI for retrieving the next batch. This URI contains the cursor value.


  • $inlinecount

  • Use this option to include records and associations count in the response. __count entry will be added to the response showing the total number of accessible records (after applying any $filter Query Options).

    Syntax:

    $inlinecount=allpages|none[/*|association-field_1,...,association-field_N]

    Examples:

    /jello/data/showbiz/Movie?$inlinecount=none (The default behavior)

    /jello/data/showbiz/Movie?$inlinecount=allpages

    /jello/data/showbiz/Movie?$inlinecount=allpages/*

    /jello/data/showbiz/Movie?$inlinecount=allpages/cast

    New project dialog

  • $debugLevel

  • Set the verbose level. Use this option to receive more details in the error message. Possible values: 1,2,3,4,... where levels of 3 and up are available only for admin users.

    Example: /jello/data/demo/Product(p-1)?$debuglevel=2

    The debug-level is available via the Java API as part of the rest request option object (Request.options.debugLevel)

  • $prettyPrinting

  • By default, Jello returns JSON responses as a compressed string, omitting all white spaces and line breaks. Use this option to return formatted results.

    Usage: /jello/data/demo/Product?$prettyPrinting=true


    Errors and response types

    More details coming soon


    Concurrency control and ETags

    * See application settings for more details


    Removing jello copyrights

    * See application settings for more details

    Last updated April 27, 2016.