Skip to content

microcks/microcks-java-client

Microcks Java Client

A Java Client or SDK that allows you to interact with the Microcks API. It has minimal dependencies and is easy to use.

GitHub Workflow Status Version License Project Chat Artifact HUB CNCF Landscape

Build Status

Latest released version is 0.0.2.

Current development version is 0.0.3-SNAPSHOT.

Fossa license and security scans

FOSSA Status FOSSA Status FOSSA Status

OpenSSF best practices on Microcks core

CII Best Practices OpenSSF Scorecard

Community

To get involved with our community, please make sure you are familiar with the project's Code of Conduct.

Versions

Java Client Microcks Version
0.0.2 1.10.0 and +

How to use it?

Include it into your project dependencies

If you're using Maven:

<dependency>
  <groupId>io.github.microcks</groupId>
  <artifactId>microcks-java-client</artifactId>
  <version>0.0.2</version>
</dependency>

or if you're using Gradle:

dependencies {
    implementation 'io.github.microcks:microcks-java-client:0.0.2'
}

Use it in your code

The API endpoints available on Microcks backend are split in different classes in the io.github.microcks.client package. Each class represents a different part of the API but needs a common client configuration that is named ApiClient.

Here's the basic usage of the client where you configure the base URI of the Microcks API:

ApiClient apiClient = new ApiClient();
apiClient.updateBaseUri("http://localhost:8585/api");

You can then easily use the client to interact with the different part of the API:

ConfigApi configApi = new ConfigApi(apiClient);
KeycloakConfig config = configApi.getKeycloakConfig();

Check the[ ]Microcks' OpenAPI reference](https://microcks.io/documentation/references/apis/open-api/) for comprehensive list of available endpoints and their parameters.

Access to authenticated endpoints

If your Microcks backend instance has enabled AuthN and AUthZ and if you need to access authenticated endpoints, we provide a KeycloakClient to first retrieve an oAuth token to use in following requests. You'll additionally need the service account name and credentials to retrieve the token (see our documentation on how Microcks is using Service Accounts).

The flow is as follows:

KeycloakConfig keycloak = configApi.getKeycloakConfig();

// If Keycloak is enabled on target backend.
if (config.isEnabled()) {
   // Build the OAuth token endpoint - here using Keycloak public url but it could be another private one.
   String tokenEndpoint = keycloak.getAuthServerUrl() + "/realms/" + keycloak.getRealm() + "/protocol/openid-connect/token";
   final String oauthToken = KeycloakClient.connectAndGetOAuthToken("<service-account>", "<service-account-credentials>", tokenEndpoint);
   
   // Set a new interceptor to add the Authorization header with the OAuth token.
   apiClient.setRequestInterceptor(request -> request.header("Authorization", "Bearer " + oauthToken));
}

// Now you can use the client to create a protected resource.
JobApi jobApi = new JobApi(apiClient);

ImportJob importJob = new ImportJob();
importJob.setName("Hello Soap Service");
importJob.setRepositoryUrl("https://raw.githubusercontent.com/microcks/microcks/master/samples/HelloService-soapui-project.xml");

ImportJob result = jobApi.createImportJob(importJob);