REST Services

REST (representational state transfer) is an architectural style, based on resources to provide inter-system communication.

The Java API specification for RESTful Web Services is called JAX-RS. It provides portable APIs for developing, exposing and accessing web applications designed and implemented in compliance with principles of REST architectural style.

Axon.ivy uses the reference implementation libraries of JAX-RS called Jersey.

Call a remote REST Service

To call a remote REST service it has to be defined in the REST Clients. After that a REST Client Activity can be used to call the REST service.

Examples can be found in the ConnectivityDemos project.

Provide own REST Services

To provide a custom REST service from an ivy project, JAX-RS annotations can be used. A REST resource is created by adding a Java class to the src directory. The Java class has to use the correct annotations (as shown below), then it will be detected as a REST resource and published automatically. After publishing, the resource will be available on the base path /ivy/api/.

/**
 * Provides the person REST resource
 * on the path /ivy/api/myApplicationName/person
 */
@Path("person")
public class CustomProjectResource {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Person get() {
        Person p = new Person();
        p.setFirstname("Renato");
        p.setLastname("Stalder");
        return p;
    }
}

Further information is available in the JAX-RS API Specification.

Many example REST services are available in the ConnectivityDemos.

Secure APIs

REST APIs served by the Axon.ivy Engine are protected by default to provide safe interactions with your API clients.

Basic auth

REST APIs are protected with Basic authentication so that only known users of the security system can get valid responses. Setting HTTP Basic authentication headers from an API client is simple and widely supported. However, since HTTP Basic headers can be easily decrypted, it is strongly recommend to allow only encrypted HTTPS traffic on the REST APIs.

You can customize the authentication for a specific API method by setting security annotations headers:

@PermitAll: allows unauthenticated access to anonymous users
@RolesAllowed: users must be authenticated and own the defined roles
@DenyAll: nobody is allowed to invoke this service

The security annotations can be reviewed in the Secure Service within the ConnectivityDemos.

CSRF protection

To call a modifying REST service via PUT, POST or DELETE the caller needs to provide a HTTP header called X-Requested-By with any value e.g. ivy. The CSRF filter protects REST services against cross-site request forgery (CSRF). If a client omits the header on a modifying REST request, the response will indicate a failure with the HTTP status code 400 (Bad Request).

User provided REST services via GET, HEAD or OPTIONS should therefore be implemented in a way that they don’t modify data.

The CSRF protection filter is enabled by default. However, it can be turned off in an environment where the client can be trusted (e.g. intranet). See the property REST.Servlet.CSRF.Protection in the ivy.webserver.yaml

Workflow API

Axon.ivy provides a basic Workflow API REST Service. It can be used to enable remote systems to request information about tasks of a user etc.