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 /<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 specification. You only need to share the specification as 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/openapi.json

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. What’s more, you may like to expose and explain technical implementation details, such as strictly required params or possible response statuses. All of these docs, can be provided by adding optional OpenAPI annotations to your REST APIs.

The highlighted lines in the following example show frequent use cases of 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¶

All OpenAPI services can be easily inspected 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.

The API Browser can be accessed with a webbrowser of your choice under the following URL paths:

In the Axon Ivy Designer: /designer/api-browser (e.g. http://localhost:8081/designer/api-browser)
In the Axon Ivy Engine: /system/api-browser (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 can be easily decrypted, it is strongly recommend to allow only encrypted HTTPS traffic on the REST APIs.

You can customized 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 client omits the header on a modifying REST request, the reponse 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.