Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Texo/JSON REST Web Services"

(Query)
(Query)
Line 84: Line 84:
  
 
You can also do a query like this:
 
You can also do a query like this:
* [http://localhost:8080/org.eclipse.emf.texo.web.example/jsonws?query=select e from Writer e| http://localhost:8080/org.eclipse.emf.texo.web.example/jsonws?query=select e from Writer e]
+
* [http://localhost:8080/org.eclipse.emf.texo.web.example/jsonws?query=select%20e%20from%20Writer%20e| http://localhost:8080/org.eclipse.emf.texo.web.example/jsonws?query=select e from Writer e]
  
 
using the query parameter. Some notes:
 
using the query parameter. Some notes:

Revision as of 08:25, 3 April 2012

Introduction

Texo JSON web services allow you to connect client-side user interfaces to a standard JPA enabled web container. The client side can be based on a RIA library such as sencha/extjs or a mobile web solution. In the future also RCP clients will be supported.

The Texo JSON web service support uses the Texo runtime libraries.

The Texo JSON webservice support the following operations:

  • Retrieve using GET http requests: using queries, requesting individual objects, all instances of a type
  • Delete operation through the HTTP Delete method
  • Update and Insert through POST/PUT

On each request Texo returns a structured response based on a schema. The response contains retrieved data, metadata (like record count), updated objects and result information.

Response Model

When doing a request, Texo will return JSON which follows a specific model, either the domain model or a special Texo response model. The response model is defined by this ecore file. There are 3 types which can be returned:

  • ErrorType: returned when an error occurs, it contains a message, stacktrace and additional information
  • ResponseType: is returned for a retrieval/GET operation for a set of objects, when a single record is requested (see specific section on retrieval below), then the record itself is returned, so no specific response type
  • ResultType: is returned for a delete/update/insert operation, it returns the complete objects that have been deleted, inserted or updated.

Update/delete/insert operations can be executed for multiple objects in one is executed for multiple objects in one request. One request is always executed in one transaction, if one record fails, the operation also fails for the other records and an ErrorType response is returned with a HTML 500 status code.

Test Tools

You can use browser extensions to test web service calls directly from your browser:


Texo-rest-client.png

Retrieve - Individual - Paging

All retrieve operations use the GET http method.

All instances of a type

To get all instances of a type, just specify the url with the type names:

The returned json is structured like this:

{
  "endRow": 4,
  "_eclass": "response|ResponseType",
  "totalRows": 5,
  "status": "success",
  "startRow": 0,
  "data": [{
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 2,
    "db_Id": 1,
    "_id": "1",
    "name": "George Orwell",
    "_title": "George Orwell"
  }, 
  ...
  ...
  {
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 1,
    "db_Id": 5,
    "_id": "5",
    "name": "New One",
    "_title": "New One"
  }],
  "_title": "success"
}

Return Information

The returned object has several properties:

  • endRow: the row number of the last row in the result
  • startRow: the row number of the first row in the result
  • totalRows: the total number of rows in the database
  • data: the returned objects

Query

You can also do a query like this:

using the query parameter. Some notes:

  • any jpql query is allowed as long the select statement contains one single object
  • a query can be combined with paging parameters (see next section)

Paging Parameters

The above examples returned sets of data. You can pass paging parameters to limit the return to a specific set of rows. This is useful when scrolling through a grid with a large dataset. The following url parameters are supported:

  • firstResult: the starting row number
  • maxResults: the maximum number of rows to return

For example: http://localhost:8080/org.eclipse.emf.texo.web.example/jsonws/library%7CWriter?firstResult=10&maxResults=10

Preventing Count

When returning sets of data Texo will do a count of all records in the database. This count operation can be expensive. To prevent it pass the noCount=true url parameter. For example:

http://localhost:8080/org.eclipse.emf.texo.web.example/jsonws/library%7CWriter?firstResult=10&maxResults=10&noCount=true

Even if no explicit count is done, still Texo will try to be smart and check if there are more records in the database then requested. If so then the endRow property of the returned JSON object will be 1+maxResults.

Individual Object Requests

When a request is done for a single object, like this:

http://localhost:8080/texo/jsonws/library%7CWriter/1

Then the record/object is returned as it is, so no special ErrorType/ResponseType/ResultType is returned.

{
  "author": {
    "_eclass": "library|Writer",
    "db_Id": 22,
    "_id": "22",
    "_proxy": true,
    "_uri": "http://localhost:8080/org.eclipse.emf.texo.web.example/jsonws/library|Writer/22#",
    "_title": "adhibendis ut liberum studio a"
  },-
  "_eclass": "library|Book",
  "category": "MYSTERY",
  "title": "libertatis iustae servitus propria oppressus",
  "db_version": 1,
  "db_Id": 65,
  "_id": "65",
  "pages": 25,
  "_title": "libertatis iustae servitus propria oppressus (25) - Mystery"
}

If the record which is requested does not exist then an ErrorType response is returned with a 404 HTML status code.

Object MetaData

The example in the previous section shows that the JSON of each object contains metadata. Texo will add these properties to each JSON object which represents a Texo/Model object:

  • _eclass: a unique identification of the EClass: EPackage prefix, EClass name, separated by a |
  • _id: the id of the object
  • _title: a displayable identification of the object, see the next section for a description
  • _proxy: used for references, is set to true if the referenced object has not been read completely yet, in that case the _uri property is also set.
  • _uri: is added to each proxy reference, denotes the uri by which the referenced object can be retrieved.

Object Title Configuration

When an object is sent from the server to the client Texo will add a title property which you can use to display a reference to the object in a grid or form. The title definition is done through EAnnotations in the model.

  • Expression: on EClass level an expression can be set using EStructuralFeatures from the EClass (referred to using a ${...} notation). It is set as an EAnnotation with source: 'org.eclipse.emf.texo' and key: 'title'. The value of the EAnnotation contains the expression. See the example in the library.ecore file in the example project:


Texo-title-config.png
  • EAnnotation on one or more EStructuralFeatures: using the same source/key as in the previous bullet but without setting the value. The EAnnottion in this case is only used to flag the EStructuralFeature. If more than one EStructuralFeature is annotated then the ' - ' (dash) is used as the separator.
  • Default: if no expression is used and no EStructuralFeature is annotated then Texo will use the following logic to compute the title, in the following order:
    • uses the first String EAttribute, if not found:
    • uses the first EAttribute, if not found:
    • uses the first EReference

It is possible to use an EReference as part of a title definition, if the reference is set then the title of the referred object is used.

Insert/Update Operation

Insert or update are done through a POST/PUT operation. Texo does not make a distinction between POST/PUT or insert/update from a request perspective. Both types of requests are handled in the same way. If the object which is being posted/put already exist in the database an update is executed, if it does not exist then an insert is executed. The ResponseType will return the inserted or updated objects.

Also the type which gets inserted/updated is not necessarily inferred from the URL, it is read from the _eclass property in the JSON data itself.

As an example, these URLs will both work fine for update/insert:

Now let's go through some examples:

Insert Example

Create one instance of a writer.

url:

Posted data:

{
  "books":[],
  "_eclass":"library|Writer",
  "name":"George Orwell"
}

Return:

{
  "inserted": [{
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 1,
    "db_Id": 2,
    "_id": "2",
    "name": "George Orwell",
    "_title": "George Orwell"
  }],
  "_eclass": "response|ResultType",
  "updated": [],
  "deleted": [],
  "_title": ""
}

The returned JSON contains the inserted object with all its information. This includes its database id and version number. Also other information can have changed or have been added on the server. The client needs to know about this, so you can update the client object using this same information.


Update/Insert with multiple records

The above example worked with one object, the same can be done for multiple objects by using an array:

The posted data:

[{
  "books": [],
  "_eclass": "library|Writer",
  "name": "Gerge Owell"
}, {
  "books": [],
  "_eclass": "library|Writer",
  "name": "Stephen King"
}]

The result:

{
  "inserted": [{
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 1,
    "db_Id": 1,
    "_id": "1",
    "name": "Gerge Owell",
    "_title": "Gerge Owell"
  }, {
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 1,
    "db_Id": 2,
    "_id": "2",
    "name": "Stephen King",
    "_title": "Stephen King"
  }],
  "_eclass": "response|ResultType",
  "updated": [],
  "deleted": [],
  "_title": ""
}

Updating

Now let's update an object, in the previous example we made some typos in George Orwell's name, let's correct them. To update an object 2 properties need to be set: _id and _eclass. These are used by Texo to find the object in the database.

The posted data:

{
  "books": [],
  _id: 1, 
  "_eclass": "library|Writer",
  "name": "George Orwell"
}

The return:

{
  "inserted": [],
  "_eclass": "response|ResultType",
  "updated": [{
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 2,
    "db_Id": 1,
    "_id": "1",
    "name": "George Orwell",
    "_title": "George Orwell"
  }],
  "deleted": [],
  "_title": "George Orwell"
}

As you can see now the updated property of the response is set, the db_version has been incremented and the correct name has been set.

Combining New/Existing objects in one request

You can also pass new and existing objects in one array, Texo will automatically detect what to update and what to insert.

The posted data:

[{
  "books": [],
  _id: 1, 
  "_eclass": "library|Writer",
  "name": "George Orwell"
},
{
  "books": [],
  "_eclass": "library|Writer",
  "name": "New One"
}]

The return:

{
  "inserted": [{
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 1,
    "db_Id": 5,
    "_id": "5",
    "name": "New One",
    "_title": "New One"
  }],
  "_eclass": "response|ResultType",
  "updated": [{
    "books": [],
    "_eclass": "library|Writer",
    "db_version": 2,
    "db_Id": 1,
    "_id": "1",
    "name": "George Orwell",
    "_title": "George Orwell"
  }],
  "deleted": [],
  "_title": "George Orwell"
}

Delete Operation

Error Response

Type/EClass Name Qualifying

Texo web services support REST-like url's such as this one to retrieve a single record:

http://localhost:8080/texo/jsonws/library%7CWriter/1

The request type is denoted as this: library|Writer. This is the name space prefix and the eclass name separated by a | symbol. This is to prevent resolving conflicts if there are several epackages with the same eclass name. You can also use this simpler form:

http://localhost:8080/texo/jsonws/Writer/1

This will iterate over all epackages registered in the Texo runtime to find the first EClass with the name Writer. This works fine in most cases as most of the time there are no name clashes.

Future Topics

The JSON web service is in active development. On the short term the following features are expected to be delivered:

  • sorting: on one or more EStructuralFeatures
  • criteria/filter api using JSON
  • allow querying for arrays of objects also
  • multiple delete/insert/update actions in one request

Back to the top