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:
header section (header)
the response section (response)
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/extensionLegacy endpoint:
http//host:port/app/_plugins/WXM_RESTAPI/page/extensions/invoke.jspzMethod: 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
| Code HTTP | API Code | Definition |
|---|---|---|
EndPoint: list of available extension services
since 11.12
GET http://host:port/app/api/json/catalog/extensionLegacy endpoint:
http//host:port/app/_plugins/WXM_RESTAPI/page/catalog/extension.jspzSupported 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
| Code HTTP | API Code | Definition |
|---|---|---|
403 | 403/701 | inaccessible catalogue (prohibited) |