By Acellam Guy

@mistaguy

1. Consume JSON REST based services

2. Publish data or microflows through REST API's

3. (Real time) Synchronization of data between Mendix applications

By Acellam Guy

@mistaguy

REST ?

•  REST stands for Representational State Transfer

•  Build Web services that are lightweight, maintainable, and scalable

• A service based on REST is called a RESTful service

• REST is not dependent on any protocol

By Acellam Guy

@mistaguy

Features of a RESTful webservice

• Representations

• Messages

• URIs

• Uniform interface

• Stateless

• Links between resources

• Caching

By Acellam Guy

@mistaguy

Representations

• Resources and how to provide access to these resources

• Format of representation JSON,XML ,etc

• Both client and server should be able to comprehend format of representation

• A representation should be able to completely represent a resource

• The representation should be capable of linking resources to each other

By Acellam Guy

@mistaguy

Messages

• Contains the actual data and metadata about the message

• Based on HTTP 1.1

By Acellam Guy

@mistaguy

URI

• The job of a URI is to identify a resource or a collection of resources

• The actual operation is determined by an HTTP verb

Eg.http://localhost:8080/Persons/1This URL has following format: Protocol://ServiceName/ResourceType/ResourceID

By Acellam Guy

@mistaguy

Uniform Interface

• Systems should have a uniform interface. HTTP 1.1 provides a set of methods, called verbs, for this purpose

Method Operation performed on server Quality

GET Read a resource. Safe

PUT Insert a new resource or update if the resource already exists. Idempotent

POST Insert a new resource. Also can be used to update an existing resource. N/A

DELETE Delete a resource . Idempotent

OPTIONS List the allowed operations on a resource. Safe

HEAD Return only the response headers and no response body. Safe

By Acellam Guy

@mistaguy

Statelessness

• Does not maintain the application state for any client

• A request cannot be dependent on a past request and a service treats each request independently

A stateless design looks like so:Request1: GET http://MyService/Persons/1 HTTP/1.1Request2: GET http://MyService/Persons/2 HTTP/1.1Each of these requests can be treated separately.

A stateful design, on the other hand, looks like so:Request1: GET http://MyService/Persons/1 HTTP/1.1Request2: GET http://MyService/NextPerson HTTP/1.1

By Acellam Guy

@mistaguy

Links Between Resources

• A resource representation can contain links to other resources like an HTML page contains links to other pages

• The user does not need a map before coming to a website

• A service can be (and should be) designed in the same way

By Acellam Guy

@mistaguy

Caching

• Caching is the concept of storing the generated results and using the stored results instead of generating them repeatedly if the same request arrives in the near future

By Acellam Guy

@mistaguy

Mendix REST Module

•  Mendix 4.4.4+ or Mendix 5.3.1+

• If you want to publish REST services or use the data synchronization features, addIVK_OpenServiceOverview to your main navigation. add StartPublishServices to the startup sequence of your application

• map your administrative project role to the Administratorrole in the RestServices for admin features

• The 'rest/' request handler needs to be opened if running in the Mendix Standard Cloud (or on premise).

• strongly recommended to not use the default HSQLDB engine if you want to publish RestServices while running locally

By Acellam Guy

@mistaguy

Consuming REST services

•  The operations in the 'Consume' folder of the module provide the necessary tools to invoke data

• The core of all these operations is the java action request

By Acellam Guy

@mistaguy

The REQUEST java action

• Request performs an HTTP request and provides the means to both send data and receive data over HTTP

• Parameters

• Method : HTTP 1.1 verbs

• URL : location of the service

• optRequestData : provides parameters

• optResponseData : provides response

• ResquestResult : HTTP response

• sendWithFormEncoding

By Acellam Guy

@mistaguy

RequestResult Object

• contains the meta information of a response

• Response code

• Etag

• ResponseBody :the full and raw response body of the request.

By Acellam Guy

@mistaguy

Sending Request Headers

• addHeaderToNextRequest : will add a header to the next (and only the next) request that will be made by the current microflow

By Acellam Guy

@mistaguy

Authentication

• Only supports Basic authentication out of the box

• Other authentication mechanism such as Oauth can be integrated

By Acellam Guy

@mistaguy

Consume Methods

• get :Tries to retrieve an object from the provided resourceURL

• get2: Similar to get, but also accepts a requestData parameter

• ?q=Rest%20Services‘

• getCollection : gets a list of objects. JSON array

• getCollectionAsync

• post

• delete

• put

• getRequestConsumerError

By Acellam Guy

@mistaguy

Template URLS

• This makes it possible to substitute values directly in an URL

By Acellam Guy

@mistaguy

Publishing webservices

• Publishing operations, based on a single microflow.

• Publishing a part of your data model, and providing a typical rest based API to retrieve, update, delete, create and even real-time sync data.

• PLEASE NOTE THAT TO BE ABLE TO PUBLISH ANY SERVICE, THE MICROFLOW STARTPUBLISHSERVICES SHOULD BE CALLED DURING STARTUP OF THE APP!

• Accessible via http://apphost/rest/yourservice

By Acellam Guy

@mistaguy

Publishing a microflow

• similar to publishing a webservice

•  instead of SOAP it uses JSON based messages

• Has a single transient object as argument.

• Each field in this transient object is considered a parameter (from HTTP perspective)

•  The return type of the microflow should be a transient object or a String or a filedocument

• Publish by calling CreateMicroflowService with the microflow that provides the implementation

By Acellam Guy

@mistaguy

Microflow with template path

• Allows for constructing more complex URLs, from which values are parsed

Eg.

groups/{groupId}/users/{userId}

http://myapp.com/rest/groups/123/users/John

By Acellam Guy

@mistaguy

Publishing a data service

• JSON based API to list, retrieve, create, update, delete and track objects in your database

• Documentation is generated automatically

By Acellam Guy

@mistaguy

End points on the service

By Acellam Guy

@mistaguy

How the data service works

• persistent entity in your database acting as data source

• transient object that acts as view object of your data

• Publish Microflow has the responsibility of converting source objects into view objects

• Update Microflow is responsible for transforming a view as provided by some consumer into real data in your database

• Each source object should be uniquely identifiable by a single key attribute

By Acellam Guy

@mistaguy

Example

• GET <your-app>/rest/<service name>/<identifier> 

By Acellam Guy

@mistaguy

Creating a new webservice

• Add IVK_OpenServiceOverview to your navigation and create a new Published Service after starting your app

• best practice is to use the GetOrCreateDataService microflow in the startup microflow to create your service configuration

By Acellam Guy

@mistaguy

Configuring the service

• Its done on the form or the create service microflow

• Core configuration are:

• Name

• Description

• Source Entity

• Source Key Attribute

• Source Constraint : xpath

• Authentication Role

• On Publish Microflow

• On Update Microflow

• On Delete Microflow

By Acellam Guy

@mistaguy

Features

• Enable GET : HTTP GET

• Enable Listing : HTTP GET

• Enable Update : HTTP POST or PUT

• Enable Create : HTTP POST

• Enable Delete : HTTP DELETE

• Enable Change Log: caching

• Enable Strict Version:

By Acellam Guy

@mistaguy

Securing Published webservice

• *

• Rolename

• Module.Microflowname : Authentication details found in the header eg key

By Acellam Guy

@mistaguy

JSON Serialization

• Converts transient object to JSON

• Nearest json type

• For each owned reference that points to a transient object, another key/value pair is added to the object

• For each owned referenceset that points to a transient object, the same approach is taken, except that the value is an array ([])

• Manual serialization process by use of serializeObjectToJson java action.

By Acellam Guy

@mistaguy

By Acellam Guy

@mistaguy

JSON Desrialization

• an be triggered manually by calling deserializeJsonToObject

• Converts the json from the consumer into a mendix transient object

• key/value pair for primitive attribute in transient object

• If the primitive is of type string, but the member with the same name in the transient object is a reference, the process assumes that the string value represents an url.

• If the member in the target object is a reference, and the value is a JSON object, a new object of the child type of the reference is instantiated

• If target is reference set and JSON is array then reference set is created

By Acellam Guy

@mistaguy

By Acellam Guy

@mistaguy

Assignment

• Consume the twitter rest API and show the recent tweets for your profile

By Acellam Guy

@mistaguy

References

• http://www.drdobbs.com/web-development/restful-web-services-a-tutorial/240169069

• https://github.com/mendix/RestServices