Page Comparison

Introduction

It is possible to create your own REST services in Java, using the plug-in base. There is a plug-in, LABS_RESTAPI_EXT, with examples.
The principle is to create a plug-in with a dedicated class and to configure a service by the administration.

Create a plug-in

Copy the following libraries to the lib folder:

• restapiext.jar

• jsonquery.jar

• wedia-packaged.utils.jar

PluginLifeCycle

It is necessary to create a class extending AbstractPluginLifeLifeCycleBusinessService (or modify the existing one if necessary), to manage the startup or stop of the extension.
To start the service, call fr.wedia.rest.serviceext.ServiceExtensionFacade.createService (plugin, restpluginName). The first parameter is the instance of the current plugin and the second parameter is the name of the REST API plugin. To stop the service, call fr.wedia. rest.serviceext.ServiceExtensionFacade.shutdown().

For example (here it is possible to configure the name of the remaining plug-in in a plug-in parameter, called restplugin):

public class PluginLifeCycleService extends AbstractPluginLifeCycleBusinessService {

	@Override
	public void startup() {
		super.startup();
		IPlugin plugin = getIPlugin();
		String restpluginName;
		try {
			restpluginName = plugin.getParameter("restplugin").getValueWithDefault();
		} catch (ParameterPluginUnknown e) {
			restpluginName = "WXM_RESTAPI";
		}
		ServiceExtensionFacade.createService(plugin, restpluginName);

	}

	@Override
	public void shutdown() {
		ServiceExtensionFacade.shutdown();
		super.shutdown();
	}

}

Create a class to implement the service

Several service bases are provided to implement different types of services, depending on the response you want to generate.

fr.wedia.rest.serviceext.BasicExtensionService

Allows you to do any type of service. Only the serialization of exceptions is processed. An object is opened in the response stream and the createResponse method will be implemented to generate the desired content for this object.

JSON sample

The form of the response generated without any particular implementation in the class is

{

}

fr.wedia.rest.serviceext.StandardExtensionService

A prestressed service to organize the response according to basic service standards, especially view services.
The response is organized into sections and sub-sections:

1. header section (header)

2. the response section (response)

3. End section (trailer)

JSON sample

The form of the response generated without any particular implementation in the class is

{
	"servicename": // nom du service,
	"servicedescription": // description du service,
	"response": {},
	"links": {
		"href": // url standard d’appel du service
	},
	"status": 200,
	"time": 11
}

Overall principle

When a service is invoked, a context is created. This context makes it possible to know the query carried out (its parameters for example) and to construct the answer (write "Json" in the response flow for example).

Configuration

Each extension service is associated with an identifier name, and a configuration JSON.

Example

{
	"pluginname": // the name of the plugin where the class is,
	"Description": // means a description,
	"classname": // the full name of the class,
	"methods": // list of accessible methods
}

Properties and sections

• pluginname: the name of the plug-in where the service implementation class is located

• description: the clear description of the service

• classname: the full name of the class that implements the service

• methods: the HTTP methods that can be used to invoke the service
  Be careful to use the correct method depending on what service or not to do.
  Here is a non-exhaustive list of methods:

  • GET: a method for a resource recovery service;

  • HEAD: in general, when the service supports GET, you also put HEAD, which allows you to do the same thing as GET, but without any content being included.

  • POST: a method for a service that creates resources

  • PUT: a method for a service that modifies resources.

  • PATCH: a method for a service that partially modifies resources

  • DELETE: a method for a service that deletes resources

• lazy: a boolean that indicates how the service is started.

  • false: (default) service only starts when called (the first call is started)

  • true: the service is mounted when starting the REST API plug-in

• delayed: a boolean to manage the feed and content type
  By default, the services are designed to generate a type of JSON content and the feed is set to autoflush, so that anything written is sent directly to the response feed.
  If you want to be able to return a different type of content, you must set the flux in delayed = true. On the other hand, as soon as we know that we are going to write JSON, it is necessary to start and open the feed explicitly. Both the BasicExtensionService and StandardExtensionService implementations do so as soon as processing begins, in the initInvocation method. Redefining the method can allow you to take control of this process in order to send content of a different type than JSON.

• pluginResourceBundle: a boolean that allows to impose the resource bundle of the plug-in extension instead of the REST API.

• logger: the name of the logger used (or null to use the standard logger of the REST API).

• secured: by default to true, disables the service invocation security, so that it can be completely processed in the implementation.

End points

Two endpoints are available:

• to invoke a service

• to retrieve the list of services

End point: invoking a service

since 11.12

GET http://host:port/app/api/json/extension

Legacy endpoint:

http//host:port/app/_plugins/WXM_RESTAPI/page/extensions/invoke.jspz

Method: depends on service configuration

Parameters

• service: character string, service name

• any other parameters required by the implementation of the service

Response format

depends on the implementation of the service

Security

The action extension_invoke of the RESTAPI domain allows to manage the endpoint call authorizations.
There are two parameters:

• surfer: surfer

• extensionName: the action identifier used

...

Error codes

...

EndPoint: list of available extension services

since 11.12

GET http://host:port/app/api/json/catalog/extension

Legacy endpoint:

http//host:port/app/_plugins/WXM_RESTAPI/page/catalog/extension.jspz

Supported methods: GET, HEAD

Parameters

• service: string, an optional filter of regular expression type (default is to display all configured extensions)

Response format

{
	"catalog": "List of extension services",
	"request": {
		"parameters": {}
	},
	"response": {
		"data": [ {
			"name": // service identifier,
			"description": // service description,
			"status": // service status
		},
		{
			"name": // service identifier,
			"description": // service description,
			"status": // service status
		},
		{ "name": // service identifier,
			"description": // service description,
			"status": // service status
		}
		]
	},
	"links": {
		"href": "http://localhost:8080/EngineTomcat6/_plugins/WXM_RESTAPI/page/catalog/extension.jspz"
	},
	"status": 200,
	"time": 187
}

The values for the status field are:

• disabled: the plug-in of the extension is disabled

• not mounted: the service is not started (has never been called, or not started if lazy=false)

• bad configured: there is an error in the service configuration

• error: the service cannot be called because of an error

• available: the service is available and can be called up

Security

The catalog action of the RESTAPI domain allows to manage the endpoint call authorizations. There are two parameters:

• surfer: surfer

• endPoint, with the extension value.

Error codes