ServiceAPI Plugin Example

Why?

The 811 ServiceAPI documentation contains a very simple example of a ServiceAPI plugin.  This example takes it one step forward and demonstrates hows to participate in the ServiceAPI pipeline to get a database connection for the current user.

Your Service

The service below inherits from the class TrimServiceBase which provides you with the property called 'Database'.  This is the best way to get a database connection for the current user as it uses the same mechanism to acquire (and release) a connection as used by every other service in the ServiceAPI.

namespace ServiceAPIPlugin
{

    [Route("/Simple", "GET")]
    public class Simple
    {
        public long Uri { get; set; }
    }

    public class SimpleResponse
    {
        public string Name { get; set; }
        public string RecordTitle { get; set; }
    }

    public class SimpleService : TrimServiceBase
    {
        public object Get(Simple request)
        {
            SimpleResponse response = new SimpleResponse();
            if (request.Uri > 0)
            {
                Record record = new Record(this.Database, request.Uri);
                response.RecordTitle = record.Title;
                response.Name = this.Database.CurrentUser.FormattedName;
            }
            return response;
        }
    }
}

Wire it up

To wire this service into the ServiceAPI:

  • create a project using the above code (or download the complete sample below),
  • copy the file ServiceAPIPlugin.dll to your ServiceAPI bin folder, then
  • add the XML below to the root of your hptrim.config.
<pluginAssemblies>
    <add name="ServiceAPIPlugin" />
</pluginAssemblies>

A JSON response

You can get a JSON response from this service simply by calling it with the appropriate URL, for example:

http://localhost/HPRMServiceAPI/simple?uri=9000000000&format=json

A Razor response

Of course you can also get a Razor response (and you can wire your service up in WebDrawer exactly as you do in the ServiceAPI).  The simplest way to get a Razor generated HTML response is to:

  1. create a file called SimpleServiceResponse.cshtml in the ServiceAPI (or WebDrawer) Views folder, and
  2. put some content similar to what you see below in it.
@using HP.HPTRIM.Service
@using ServiceStack;

@inherits TrimViewPage<ServiceAPIPlugin.SimpleResponse>

<h1>My name is: @this.Model.Name</h1>

<h2>The title of record @this.Request.QueryString["uri"] is @this.Model.RecordTitle</h2>

A complete example

This project contains all you need to create this project in HPRM 811.  Some things to look out for:

  • references to standard ServiceAPI and ServiceStack DLLs,
  • a reference to HP.HPTRIM.SDK.dll to allow us to use the .Net SDK,
  • the service follows the ServiceStack convention of request/response/service, and
  • the method Get in the service is for GET requests.  If you need to update HPRM add a Post method and a new request to use as the parameter in that method (analogous to the 'Simple' class.

Warning

The name of one of the referenced DLLs in the project above will likely change in a future release of HPRM and will necessitate a changing of the reference and a re-compile of the project for it to continue to work.

Written on May 13, 2015