HTTP Service

Contents

HTTP Service enable mouting of http controllers safely made available within an application (or site’s) url space, without the use of routers. Due to the URL-pattern created, an http service will never conflict with other application url patterns. Services are in particular useful when used in the Site engine or webapps where URLs are not predictable.

Controller

To create a service, place an http controller file in the src/main/resources/services/ structure of your project. Each controller needs to be placed in a folder matching it’s name i.e.: src/main/resources/services/myservice/myservice.js

Example service controller

src/main/resources/services/<service-name>/<service-name>.js
exports.get = function(req) {
  return {
    body: {
      time: new Date()
    },
    contentType: 'application/json'
  };

};

Endpoint

Services use the following mount pattern: **/_/service/<appname>/<servicename>. This means that a service can be invoked in multiple locations, i.e. domain.com/_/service/.. or domain.com/some/path/_/service/... The context the service is mounted on can also be used by the controller as context.

As an example the service 'profileimage' will only work in context of a profile’s url. I.e. domain.com/profile/user1/_/service/myapp/profileimage will service an image, but invoked elsewhere it will not work.

Descriptor

By default, services may by used by any client or user. At times, it makes sense to restrict access to the service based on user roles. This can be done without custom coding.

Sample descriptor limiting access to the service:

src/main/resouces/services/<service-name>/<service-name>.xml
<service>
  <allow>
    <principal>role:system.admin</principal>
    <principal>role:myapp.myrole</principal>
  </allow>
</service>

serviceUrl()

To safely generate a service URL, use the serviceUrl() function that is part of the Portal Library.

When invoked, the function will generate a contextual service url based on the context of the current controller.

Contents

Contents