Create a new Rest API custom endpoint

Création du service

Dans un plugin, créer la classe suivante:

import java.util.HashSet;
import java.util.Set;
import com.noheto.api.basic.BasicException;
import com.noheto.extensions.interfaces.services.AbstractPluginBasicApiService;
import com.noheto.api.basic.BasicServiceAction;

public class HelloWorldRestApi extends AbstractPluginBasicApiService {

	@Override
	public Set<BasicServiceAction> getActions() {
		Set<BasicServiceAction> lst = new HashSet<BasicServiceAction>();
		lst.add(new GetHelloWorldAction());
		lst.add(new EchoAction());
		return lst;
	}

	@Override
	public void prepare() throws BasicException {
	}

	@Override
	public String getMapping() {
		return "/edocs/example/rest/*";
	}

}

Créer l’action GetHelloWorldAction:

import java.util.Arrays;
import java.util.List;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.noheto.api.basic.BasicParameterAction;
import com.noheto.api.basic.BasicServiceAction;
import com.noheto.plugins.IPlugin;

public class GetHelloWorldAction extends BasicServiceAction {

	@Override
	public void execute(IPlugin plugin, HttpServletRequest request, HttpServletResponse response) throws Throwable {
		response.getWriter().println("Hello World!");
	}

	@Override
	public String getAcceptPathInfo() {
		return "/getHelloWorld";
	}

	@Override
	public String getHelpMethod() {
		return "Retourne HelloWorld";
	}

	@Override
	public List<BasicParameterAction> getExposedParameters() {
		return null;
	}

	@Override
	public Iterable<String> getAcceptedRequestMethods() {
		return Arrays.asList("GET","POST");
	}

}

Créer l’action EchoAction:

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.noheto.api.basic.BasicParameterAction;
import com.noheto.api.basic.BasicServiceAction;
import com.noheto.plugins.IPlugin;

public class EchoAction extends BasicServiceAction {

	@Override
	public void execute(IPlugin plugin, HttpServletRequest request, HttpServletResponse response) throws Throwable {
		String message = checkMandatoryParameter(request, "message");
		response.getWriter().println(message);

		String complement = getParameter(request, "complement", null);
		if (complement!=null) {
			response.getWriter().println(complement);
		}
	}

	@Override
	public String getAcceptPathInfo() {
		return "/echo";
	}

	@Override
	public String getHelpMethod() {
		return "Retourne le message indiqué et le complément si il y en a un.";
	}

	@Override
	public List<BasicParameterAction> getExposedParameters() {
		List<BasicParameterAction> params = new ArrayList<BasicParameterAction>();
		params.add(BasicParameterAction.create().setName("message").setMandatory(true).setDescription("Quel message retourner ?"));
		params.add(BasicParameterAction.create().setName("complement").setMandatory(false).setDescription("Message complémentaire ?"));
		return params;
	}

	@Override
	public Iterable<String> getAcceptedRequestMethods() {
		return Arrays.asList("GET","POST");
	}

}

Déployer le plugin

Afficher la documentation

Pour afficher tous les ordres possibles de ce service et la documentation de chacun, il faut appeler l’url déclaré dans le mapping du service.

curl http://localhost/contextpath/api/edocs/example/rest/

Appeler l’action GetHelloWorld

curl http://localhost/contextpath/api/edocs/example/rest/getHelloWorld

Appeler l’action Echo

curl "http://localhost/contextpath/api/edocs/example/rest/echo"
curl "http://localhost/contextpath/api/edocs/example/rest/echo?message=kkk"
curl "http://localhost/contextpath/api/edocs/example/rest/echo?message=kkk&complement=ccc"

Sécuriser le service

N’autoriser les appels que par une utilisateur applicatif

Pour que le service ne soit utilisable que par un utilisateur applicatif authentifié, alors il faut modifier le service pour implémenter la méthode "isSecuredByApplicatifUser()".

@Override
public boolean isSecuredByApplicatifUser() {
    return true;
}

L’url d’appel sera maintenant:

curl "http://localhost/contextpath/api/edocs/example/rest/getHelloWorld" -u "login:pass"
curl "http://localhost/contextpath/api/edocs/example/rest/echo" -u "login:pass"

N’autoriser les appels que par une utilisateur administratif

Pour que le service ne soit utilisable que par un utilisateur administratif authentifié, alors il faut modifier le service pour implémenter la méthode "getAcceptedAdminUserRoles()".

	@Override
	public Set<String> getAcceptedAdminUserRoles() {
		Set<String> lst = new HashSet<String>();
		lst.addAll(Arrays.asList("Administrators", "TestOperators", "..."));
		return lst;
	}

L’url d’appel sera maintenant (avec un couple login/pass administratif):

curl "http://localhost/contextpath/api/edocs/example/rest/getHelloWorld" -u "login:pass"
curl "http://localhost/contextpath/api/edocs/example/rest/echo" -u "login:pass"

Plus loin

Vous pouvez ajouter autant d’action que vous le voulez. Sur chaque action vous pouvez sécuriser les méthodes HTTP acceptables. Par exemple, les actions précédentes n’acceptent que POST ou GET, si vous tentez un appel en -XPUT, il sera rejeté.

Vous pouvez tout aussi simplement accepter la méthode PUT.