REST support for B2B access
to your AppServer
PUG Challenge Americas - 2014
Michael Jacobs : Senior Software Architect
Edsel Garcia : Principal Software Engineer
6.1.2014
OpenEdge [Rollbase] Mobile
2
© 2014 Progress Software Corporation. All rights reserved.
OpenEdge REST
3
© 2014 Progress Software Corporation. All rights reserved.
Agenda
 REST is the hardest easy thing I’ve done
 Using the tools
 Moving to Deployment
 When things go sideways
4
© 2014 Progress Software Corporation. All rights reserved.
REST is the hardest easy thing I’ve
done
5
© 2014 Progress Software Corporation. All rights reserved.
When REST Can Be The Right Choice When…
 Converting existing SOAP services to REST
 Need to call a pre-11.2 AppServer
 The AppServer requires access to HTTP request headers, cookies, & URL fields
 The REST client requires control over HTTP response headers, and cookies
 You need to support ANY type of HTTP compliant client (not limited to JavaScript)
6
© 2014 Progress Software Corporation. All rights reserved.
REST is Easy
 Client simply uses standard HTTP messages, responses, verbs, etc
 Uses standard web servers – so no firewall issues
 The REST service is just a web app and can be written in any number of languages
 Use any HTTP 1.1 enabled client
 Each REST resource is an object that has data and actions
 Each REST resource is identified using the triplicate: URL, verb, & media type
 There are NO rules
7
© 2014 Progress Software Corporation. All rights reserved.
Developing a RESTful Client API is HARD…
 There are no rules
• No formal API contact for client developer to use
– What is the list of supported REST resources?
– What verbs and media type is supported for each resource?
– What variable parameter(s) go where in the HTTP messages and responses?
 A starting point may be to think of CRUD operations and supporting functions
 Follow the same requirements as you use for your application
• Multiple simultaneous Versions
• Extensibility
• Intuitively organized sets of objects and related operations ( i.e. REST services )
• Deploy as incrementally added web application(s) and REST service(s)
• Secure (when it needs to be)
8
© 2014 Progress Software Corporation. All rights reserved.
REST to/from AppServer RPC
9
© 2014 Progress Software Corporation. All rights reserved.
A Good RESTful API Design is Essential
 Choose between one monolithic REST service versus multiple REST services
• Divide API [URL] space into web applications hosting related REST services
(example: application administration services versus application data services)
• Each REST service’s URL path is a hierarchy of related resources
• Each resource’s URL path can have one or more instance qualifiers
• Each resource’s URL path has one or more [action] verbs ( & media type)
10
© 2014 Progress Software Corporation. All rights reserved.
RESTful Web Application Design
 Each deployed (OpenEdge REST) web application has
• A web application name
• One or more REST services
• A security configuration ( user authentication and [URL] authorization )
• A connection to ONE State-free model AppServer [service]
 Example ( for OpenEdge REST web application ):
http://host:port/webAppName/rest/
deployment site defined part
11
© 2014 Progress Software Corporation. All rights reserved.
OE defined part
RESTful Service and URL Design
 What is a REST Service
• Has a service-name that appears in the URL
• A service-name contains one or more REST resources
• Each resource has a unique URL path within the service
• Each resource URL path can have
– Optional input parameters and/or options
You are here…
 Example
http://host:port/webAppName/rest/<service-name>/<resource-path>
developer designed part
12
© 2014 Progress Software Corporation. All rights reserved.
You Choose What GOES Where
HTTP message/response

Resource URL path

Resource URL options

Resource URL query

HTTP request verb

HTTP request/response header

HTTP request/response Cookie

HTTP request/response Body
•
{external | singleton | single-run}



Object internal procedure/method
Procedure/method Input parameters
Procedure/method parameters
[tunneled RPC parameters]
PDSOE
generated
13
HTTP
to/from
AppServer
mapping
file
(.paar)
AppServer
service-interface / business-entity
 OO/procedure object path
 OO/procedure run-time model
© 2014 Progress Software Corporation. All rights reserved.
Developer
generated
Tomcat Reality
 A web server has a max number of web applications before memory is exhausted
 The more web applications – the longer to start the server
 Deleting Mobile/REST web application does not necessarily recover memory
 Low memory symptoms: hung requests, does not start, process crash, no errors logged
 Tips:
• Tip: fewer web applications
– Combine Mobile App & Service in a single WAR using PDSOE Export…
– Combine multiple REST services into a single WAR using PDSOE Export…
• Tip: turn off PDSOE auto-publish
• Tip: restart web server periodically after n publishes
14
© 2014 Progress Software Corporation. All rights reserved.
Using the tools
16
© 2014 Progress Software Corporation. All rights reserved.
Developing REST Services using PDSOE
1. Design the RESTful API’s web services and resource URL space
2. Design URLs and verbs and map them to AppServer OO classes1/procedures
3. Design the HTTP message and response for each URL & verb combination
a. Is the HTTP body a single data object or multiple RPC parameters?
4. Create OO classes/procedures in PDSOE project
5. Turn class/procedure into a ‘service interface’
6. Create REST service in PDSOE project
7. Use PDSOE’s mapper utility to map REST requests to OO class/procedure
8. Configure AppServer connection, logging, and web application security
9. Publish (Export) for development debugging
17
© 2014 Progress Software Corporation. All rights reserved.
Special Considerations for 10.2B & 11.1
 Cannot use dataset/temp-table as parameters (no automatic JSON export/import)
• Can send/receive JSON or XML as Character parameter
 Cannot use Singleton Classes in AppServer
• Can use remote, Single-Run, Singleton procedures
 No AppServer SSO by REST service
18
© 2014 Progress Software Corporation. All rights reserved.
PDSOE Features Specific to REST Service Generation
 REST, Mobile, or AppServer project
 Service Interfaces
 Business entities
 Customizing security
 Procedures, classes, and annotations
 REST mapping tool
 Publish for debug and testing (to built-in debug Tomcat version)
 Export .war web applications for production deployment
Proceed to Demo
19
© 2014 Progress Software Corporation. All rights reserved.
Moving to Production
20
© 2014 Progress Software Corporation. All rights reserved.
Moving Your REST Service to Deployment
 Update and test the REST service’s security templates [ if needed ]
 Set default logging and AppServer connection properties
 Export unit tested REST service from PDSOE as a .war file
 Use a production configured Tomcat web server
 Use Tomcat tools to deploy your service’s war file [ under a different name ]
 Configure the REST service’s
• AppServer connection
• Security [ appSecurity-xxxx.xml ] template in web.xml
– User account server connection
– Roles
• CORS module [ if accessed by JavaScript clients ]
• AppServer SSO
 Enable and test access to your REST service
21
© 2014 Progress Software Corporation. All rights reserved.
When things go sideways
22
© 2014 Progress Software Corporation. All rights reserved.
Debug Guide
 Tools
• A good proxy debug tool
• Turning on HTTP message tracking in the web application
• Web server logs
• Web application logs
• Web application logging configuration
 Flow
• Ping the web application
• Get the RESTful API description
• Ping the AppServer
• Access the AppServer’s RESTful API
23
© 2014 Progress Software Corporation. All rights reserved.