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 the 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, you have to define it in the REST Clients. After that, you can use a REST Client Activity to call the REST service.

Find examples in the ConnectivityDemos project.

Provide Your Own REST Services

To provide a custom REST service in your Axon 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) so it is detected as a REST resource and published automatically. After publishing, the resource will be available on the base path /<appName>/api/.

/**
 * Provides the person REST resource
 * on the path /myApplicationName/api/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.

API Publishing

Once you have provided new REST APIs with your project, you need to share the service capabilities with your service users. This is simple, since services defined within Ivy projects will be published as OpenAPI service specifications. You only need to share the specification as a file or serve it on a public URL so that clients can start using it.

The technical interface description is available under the following URL path:

/<appName>/api/openapi.json e.g., http://localhost:8081/designer/api/openapi.json (this one is from Designer)

Custom OpenAPI Docs

The automatically generated OpenAPI specification exposes all strict service capabilities without additional effort for you as a service provider.

However, there are many service interfaces that become easier to use if they are enriched with explanatory documents. You may like to expose and explain technical implementation details, such as strictly required parameters or possible response statuses. You can provide this information by adding optional OpenAPI annotations to your REST APIs.

The highlighted lines in the following example show frequent use cases of these optional OpenAPI docs annotations.

Example OpenApiResource.java

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;

@Path("zip")
@Tag(name = "CRM") // a name that can be used to cluster similar services
public class OpenApiResource {
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  @Operation(description = "finds customers in the CRM by ZIP code") // prose text
  @ApiResponse(responseCode = "200", description = "matching persons") // possible responses
  public List<Person> findPersonByZip(
    @Parameter(required = true, example = "CH-6300", description = "a ZIP with prefixed country code")
    @QueryParam("zip") String zip, // mandatory parameter with rich docs.
    @Parameter(example = "active, inactive, suspended")
    @QueryParam("status") String status
  ) {
    return UserRepo.findByZip(zip, status);
  }
}

API Browser

You can easily inspect all OpenAPI services with the API Browser. It gives consumers of your services not only a detailed service description, but a simple client to fire real calls against the services, too.

To access the API Browser, open the URL /system/api-browser with a web browser of your choice e.g., http://localhost:8080/system/api-browser

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 are base64 encoded and thus can easily be decoded, we 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

You can review the security annotations in the demo project 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 the 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 have to be implemented such that no data is modified.

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

Workflow API

Axon Ivy provides a basic Workflow API REST Service. You can use it to enable remote systems to request information about tasks of a user etc.

Pretty printing

If you add the query param pretty to the URL to any REST Service provided by the Axon Ivy Engine which produce JSON, then you get a pretty formatted JSON e.g., http://localhost:8081/designer/api/engine/info?pretty