Code integration (REST API invocation)

Owned by Joël DRIGO
Last updated: Sept 30, 2024
3 min read

This documentation is intended to guide developers through the integration of our REST API.

We recommend using a standard library adapted to your programming language, whether low-level (HTTP) or, better still, high-level (REST), as it will provide you with the mechanisms you need to formulate your requests correctly. In particular, avoid manual management of headers, cookies and other request parameters.

Examples of libraries

Connection mechanisms and operating modes

The API supports two operating modes: sessionless and sessionful.

  • Sessionful mode: the connection is established once and maintained via the session. This mode is recommended for new environments, as it optimizes performance by reducing authentication and user context initialization time.

  • Sessionless mode: each call requires a new connection, including an authentication step and context initialization each time, which can slow down interactions.

To check which mode is active in your environment, please contact your Wedia project manager.

Session and cookie management

In sessionful mode, we recommend that you manage the JSESSIONID cookie to maintain the session. When you connect, you receive :

A short-term access token for authentication.
A long-lasting refresh token to obtain a new access token once it has expired.

Connection modes

Two connection methods are supported:

  1. JWT with Bearer Token: A JWT token is obtained via the endpoint /api/rest/signin and then transmitted in the Authorization header in Bearer form.

  2. Cookie authentication: Cookies are handled automatically by the HTTP protocol. To activate this mode, the cookieauth=true parameter must be added to the request at connection time.


For all connections, the /api/rest/signin endpoint must be called in POST mode with the following parameters:

  • login and password: user identification information.

  • application: application name.

  • cookieauth=true (if cookie mode).

In cookieauth=false mode, the JSON response contains the accessToken to be used as a Bearer, as well as the refreshToken to renew authentication.

Examples of codes and best practices

HTTPS connection

Since API environments are secured by HTTPS, it is sometimes necessary to initialize a TrustManager or SSLContext in certain languages to manage certificates correctly. Here are some examples for the various libraries and languages:

Java - Unirest

  • Version 1.4 (mashape)

    Unirest.setHttpClient(HttpClients.custom() .setSSLContext(new SSLContextBuilder().loadTrustMaterial(null, (certificate, authType) -> true).build()) .build());

  • Version 4 (kong)

    Unirest.config().sslContext(new SSLContextBuilder() .loadTrustMaterial(null, (certificate, authType) -> true).build());

Java - HttpClient (Java 11+)

SSLContext sslContext = SSLContext.getInstance("TLS"); sslContext.init(null, new TrustManager[]{new X509TrustManager() { public java.security.cert.X509Certificate[] getAcceptedIssuers() { return null; } public void checkClientTrusted(X509Certificate[] certs, String authType) { } public void checkServerTrusted(X509Certificate[] certs, String authType) { } }}, new SecureRandom()); HttpClient client = HttpClient.newBuilder() .sslContext(sslContext) .build();

Python - Requests

Ruby - Faraday

C# - HttpClient

Cookie management

Java - Unirest

  • Version 1.4

  • Version 4

Java - HttpClient (Java 11+)

JavaScript - Axios / Fetch

In the browser environment, cookies are automatically managed, but to include them explicitly:

  • Axios

  • Fetch

Environment management with Load Balancers and Reverse Proxies

When using clusters, it is crucial to follow cookie management standards, such as RFC 6265, to ensure proper management of session stickiness.

Java - Unirest

  • Version 1.4

  • Version 4

Java - HttpClient (Java 11+)

General recommendations

Always comply with the standards defined in RFC 6265 for clustered environments, and ensure that cookie management is correctly implemented. This will guarantee session stickiness, ensuring that all client requests are handled by the same node in a cluster.

Recommendation: Destroy the Token by making Signout

Although not strictly necessary, it is strongly recommended to always perform a signout to destroy the authentication token when you've finished invoking the API.

This action has two advantages:

  1. Resource release: The signout releases the server resources associated with the session.

  2. Enhanced security: It invalidates the refresh token, limiting the potential impact in the event of token theft. By invalidating the token, you prevent an attacker from obtaining a new access token with a compromised refresh token.

To perform a signout, call the endpoint /api/rest/signout in POST.

 

 

Â