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

Revision as of 05:30, 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:

• Chrome Advanced REST application
• Firefox Poster

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 Record Requests

When a request is done for a single record, 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.

Delete Operation

Error Response