HTTP Services

Contents

HTTP Services

HTTP Services are http controllers safely made available within an application (or site’s) url space. Services will never conflict with other application url patterns. Services are in particular useful for sites, where most URLs are editorially created and managed.

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/service/myservice/myservice.js

Example service controller

src/main/resources/services/<service-name>/<service-name>.js
var counter = 0;

exports.get = function(req) {

  counter++;

  return {
    body: {
      time: new Date(),
      counter: counter
    },
    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