mendix rest services
TRANSCRIPT
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