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"

(Response Model)
Line 17: Line 17:
  
 
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 [http://git.eclipse.org/c/texo/org.eclipse.emf.texo.git/tree/runtime/org.eclipse.emf.texo.server/src/org/eclipse/emf/texo/server/model/response/response.ecore this] ecore file. There are 3 types which can be returned:
 
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 [http://git.eclipse.org/c/texo/org.eclipse.emf.texo.git/tree/runtime/org.eclipse.emf.texo.server/src/org/eclipse/emf/texo/server/model/response/response.ecore 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
+
* '''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
+
* '''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.  
+
* '''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.
 
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.

Revision as of 05:59, 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 [1]] 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

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.

Insert/Update Operation

Retrieve - Individual - Paging

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 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
{
  "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"
}

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 model (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.

Delete Operation

Error Response

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
  • multiple delete/insert/update actions in one request

Back to the top