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.