Article
Eduard Lebedyuk · Jan 17, 2017 2m read

Absolute minimum you have to do to start running Ensemble REST Services

This little guide would help you start running Ensemble REST services in no time.

1. Create REST Service class, for example User.RESTService, it should:

  • Extend EnsLib.REST.Service
  • Have EnsServicePrefix parameter defined and set to "|"
  • Have XData Map and call methods (same as Caché REST brokers)

2. Add new service to your production, here's the important settings

  • Class: User.RESTService (for this example)
  • Name: should be Latin letters with no whitespaces (it's a part of the URL), for example MyService
  • Enabled: true (and production should be running)
  • To use Caché CSP port and not a custom one:
    • Enable Standard Requests: true
    • Pool Size: 0
    • Port: leave empty

3. Add new web application (once per namespace)

  • Web App Name: /rest (or any other)
  • Namespace: your namespace
  • Dispatch class: EnsLib.REST.Service (and NOT User.RESTService)

4. (Optional) Authentication

  • For unauthenticated access set web application with unauthenticated access only and add required roles (db access, etc) to UnknownUser or web application
  • For authenticated access set web application with authenticated access only (for example Password) and add required roles (db access, etc) to  the user, who would access the application. Request should contain either basic authentication or CacheUserName and CachePassword URL parameters

That's all.  Here's User.RESTService class:

Class mvk.production.DocRESTService Extends EnsLib.REST.Service
{

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]
{
<Routes>
<Route Url="/:test" Method="GET" Call="test"/>
</Routes>
}

Parameter EnsServicePrefix = "|";

Method test(pInput As %Library.AbstractStream, Output pOutput As %Stream.Object, test As %String) As %Status
{
    do pOutput.Write("Received:" _ test)
    quit $$$OK
}

}

And it should be available at:

http://server:port/webapp/itemname/[prefix]/[urlmap]

In this case as there' is no prefix defined, for the server with default settings it would be accessible at:

http://localhost:57772/rest/MyService/:test

Links:

4
0 1,065
Discussion (3)3
Log in or sign up to continue

From documentation: " Although Ensemble defines a class EnsLib.REST.Service , that is a subclass of %CSP.REST , we recommend that you not use this class because it provides an incomplete implementation of %CSP.REST ."

Instead, it's recommended that you create a REST class that extends %CSP.REST, and send data to a business service from the methods in this class.

 

Yes, subclassing %CSP.REST is much easier.

By the way, please take a look at the online course Setting Up RESTful Services that walks you through how to use %CSP.REST with your productions! This is the recommended approach.