Common concepts

This introduction will start by giving you some common information about the REST API, before walking you through the different aspects of what is provided by the Wedia REST API.

REST API Dashboard

The REST API comes with a dedicated admin dashboard, that offers many set up and monitoring options :

Open

You will need a dedicated account to access these features, as it needs a second authentication level.

The Dashboard URL is :
http://Wedia Server/app/_plugins/WXM_RESTAPI/page/home.jspz

Connection/Authentication

To gain access to the data, authentification is required before making any call to the server.

Wedia support 4 type of authentication, depending on your use cases :

• HTTP Basic authentication : uses the credential of a Wedia DAM user.

• JWT token authentication (since 11.15.0) : uses the credential of a Wedia DAM user.

  • bearer authentication

  • cookie authentication

• Application Token authentication

  These tokens are linked to special “application users” that you can be created in the REST API admin dashboard. This is an alternative to using real users credential, as with the previous authentication methods, and this authentication methods fits when the API caller is indeed an automated application, without having a user logged in. These “application users” can be active for a limited time only. To use this application token, use a basic authentification with the following header :

  • In the REST API dashboard, you will create a new Application Token, and will get in return a key and secret. The key as will serve as the login and the secret as password for a Basic authentication.

  • Please set the header for application id: X-WEDIA-REST-APPLICATION

  • You may also set the optional header (optional) for user id: X-WEDIA-REST-APPLICATION-USER

• Sessionful authentification (since 2021.4.0 ) : this allows to create a stateful session, that will be shared by all components of the application : API, Portal, BackOffice. This can be useful for recreating a full featured experience for the connected user, through the API. The session is maintained through two session based cookies : JSESSIONID cookie and x-wedia-api-token cookie.

• Please note that as of 11.15 , the Session based authentication that also exists in the API is no longer enabled in the API as it offers a CSRF-type attack surface.

Endpoints Common Parameters

All API endpoints that we will detail later are using parameters, that are common to all the calls.

This section explains these API-wide parameters.

lang

By setting this parameter you will set up which localized data you wish to get as the result of your query.

If the API is connecting on behalf of a user, most of the time this is not needed, as the user record in the database already has a default language set up. We will also use the browser language to find out the language we should return if no default language is used.

A special section about localization will help you learn more about translations, and locales.

debug

On development mode, exceptions stacktraces, and other additional debug informations, are exported to the JSON response. In production mode, any error will respond, this informations are no longer reported (since version 11.14.2)

The debug parameters will set up the mode, development or production. Its value is a boolean true (default) or false.

state

(since version 11.15.1 )

The value of this parameter is returned as it is in the response. If the “state” value is a JSON, it is directly integrated into the JSON response structure.

This information allows you to reconcile a response and a request. This is particularly useful if the client uses an asynchronous and centralized queue.

Another case could be the possibility of ignoring obsolete responses. For example, in a search system, an impatient user could restart a new search and his answer could come back before the answer of the previous search. The state will let you know that the second answer is obsolete and no longer needs to be processed.

To limit the load on response times, prefer to send an identifier (or short data structure) and manage an association map in the client to find the information that allows you to find the request (or the component that is supposed to process the response).

restapiconsumer (obsolete)

(from version 11.18.0 until 11.27.0)

This parameter was used to distinguish between API “consumers” of the REST API, in the DAM Analytics dashboard. This paramete is no longer supported, as we now provided a dedicated API for logging API-related analytics events.

Localization

The Wedia DAM stores localized data: a DAM asset caption is often available in multiple languages, with code such as “EN”, “FR”, “ES” that represent the caption in english, french, spanish…

When using the REST API, returning all the languages values for all data is often not wanted: this increases the data traffic, with locale data that is not relevant for the user that is requesting the data.

By default, the localization language is based upon the web browser language locale. If the web browser has no locale, it uses the header Accept-Language.
It is also possible to force a locale by using the request parameter lang. Its syntax is similar to the header.
If the requested language is not supported the service will respond NOT_ACCEPTABLE.

Errors

When an error is returned by the API, the HTTP status provides its HTTP error type.

The JSON response contains some additional information, such as

• A localized message for the end user

• A unique error code that allows a proper management

• In debug mode: a stacktrace

Usual errors codes

HTTP methods

By default, the server only accepts GET, HEAD or POST methods.

If you need to use other methods such as “PUT”, then te endpoint should be called with the POST method and the name of the actual method should be set in a specific header.

We support 3 alternative headers of your choice :

• X-HTTP-Method-Override (Google/GData HTTP method overwriting)

• X-HTTP-Method (Microsoft HTTP method overwriting)

• X-METHOD-OVERRIDE (IBM HTTP method overwriting)