> For the complete documentation index, see [llms.txt](https://interfacing.gitbook.io/interfacing-help-files/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://interfacing.gitbook.io/interfacing-help-files/interfacing-help-files-fr/developpeurs-de-solutions/api-and-information-repository/api-rest.md).
# API REST
IMS fournit un ensemble complet d’API REST pour s’intégrer à d’autres systèmes et créer des services automatisés. Toutes les actions réalisables dans IMS sont également disponibles via ses API.
## Premiers pas
Pour utiliser les API IMS, vous avez besoin des éléments suivants :
1. Un **compte utilisateur IMS** actif.
2. L’**URL de base IMS** de votre organisation.\
Par exemple : `https://votreims.interfacing.com`
3. Une **authentification** pour obtenir un jeton valide.
***
## Authentification et gestion des jetons
### Fonctionnement de l’authentification
* IMS utilise des **JWT (JSON Web Tokens)** pour identifier les utilisateurs.
* L’accès aux API est **basé sur l’utilisateur**, comme dans IMS.
* Vous ne voyez que les éléments autorisés pour cet utilisateur.
* Les jetons sont liés à une **session**, qui peut expirer ou être terminée.
* Les fonctions d’administration **échouent** si le jeton n’appartient pas à un administrateur.
Expiration de la session et du jeton
* **Délai d’expiration de session :**\
Défini avec `SESSION_TIMEOUT` (minutes) dans *Administration système > Onglet Avancé*.\
Le jeton devient invalide lorsque la session se termine.
* **Expiration du jeton :**\
Définie avec `WEBTOKEN_EXPIRES_IN` (jours) dans *Administration système > Onglet Avancé*.
{% hint style="info" %}
Seuls les administrateurs système peuvent modifier ces paramètres.
{% endhint %}
Terminer manuellement une session
* Accédez à **Administration système > Onglet Général**.
* Recherchez **Gérer les sessions IMS**.
* Cliquez sur 🗑️ à côté de la session pour la terminer.
### Obtenir un jeton d’accès
1. Envoyez une requête **POST** à `https://YOURIMS.interfacing.com/api/v1/login/local`\
avec un corps JSON contenant le nom d’utilisateur et le mot de passe.
2. La réponse contient un cookie nommé `access_token`.\
Utilisez ce cookie lors des appels suivants ou extrayez le jeton. Envoyez-le ensuite dans l’en-tête HTTP comme jeton Bearer.\
\
**Exemple de cet échange :**
```json
15:35:15.889 request:
1 > POST https://localhost/login/local
1 > Content-Type: application/json; charset=UTF-8
1 > Content-Length: 45
1 > Host: localhost
1 > Connection: Keep-Alive
1 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
1 > Accept-Encoding: gzip,deflate
{
"password": "Passw0rd",
"username": "myimsuser"
}
15:35:16.011 response time in milliseconds: 122
1 < 302
1 < Date: Wed, 08 Jun 2022 19:35:16 GMT
1 < Content-Type: text/plain; charset=utf-8
1 < Content-Length: 23
1 < Connection: keep-alive
1 < Cache-Control: no-store
1 < Set-Cookie: [loginsuccess=true; Path=/, access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...; Expires=Thu, 01 Jan 1970 00:00:00 GMT]
1 < Location: /
1 < Vary: Accept
1 < Age: 0
1 < Via: 1.1 varnish (Varnish/7.1)
1 < X-Frame-Options: SAMEORIGIN
1 < X-XSS-Protection: 1; mode=block
1 < X-Content-Type-Options: nosniff
1 < Referrer-Policy: no-referrer-when-downgrade
1 < Content-Security-Policy: default-src 'self' http: https: data: blob: 'unsafe-inline' 'unsafe-eval'
1 < Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
1 < X_SRV: EPC
```
**Exemple CURL :**
```bash
curl --request POST --url 'https://myims.interfacing.com/login/local' --header 'Content-Type: application/json' --data '{"username": "myecpuser", "password": "Passw0rd"}' -c /tmp/cookie.tmp
```
**Exemple de code Java avec Spring Boot :**
```java
package com.interfacing.ims.sync.bpc.client;
import java.util.Optional;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.ApplicationContextException;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseCookie;
import org.springframework.web.reactive.function.BodyInserters;
import org.springframework.web.reactive.function.client.WebClient;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import reactor.core.publisher.Mono;
import com.interfacing.epc.sync.util.WebClientUtils;
@Configuration
@RequiredArgsConstructor
@Slf4j
public class BpcWebClient {
private final WebClient.Builder webClientBuilder;
@Value("${bpc.baseUrl}")
private String baseUrl;
@Value("${bpc.username}")
private String username;
@Value("${bpc.password}")
private String password;
@Value("${bpc.wiretap}")
private boolean wiretap;
@Bean
public WebClient bpcClient() {
WebClient.Builder clientBuilder = webClientBuilder.baseUrl(baseUrl + "/api/v1").defaultHeader(HttpHeaders.AUTHORIZATION, authorization());
log.debug("BPC client created");
return WebClientUtils.build(clientBuilder, this.getClass().getPackageName() + ".bpcClient", wiretap);
}
private String authorization() {
WebClient.Builder clientBuilder = webClientBuilder.clone().baseUrl(baseUrl + "/login/local");
Optional s = WebClientUtils.build(clientBuilder, this.getClass().getPackageName() + ".authorization", wiretap)
.post()
.contentType(MediaType.APPLICATION_JSON)
.body(BodyInserters.fromValue(new LoginRequest(username, password)))
.exchangeToMono(r -> Mono.justOrEmpty(r.cookies().getFirst("access_token")))
.blockOptional();
if (s.isPresent())
{
return "Bearer " + s.get().getValue();
}
else
{
throw new ApplicationContextException("Invalid username/password for BPC");
}
}
}
```
***
## Exemple de flux de travail API
Ces exemples couvrent le cycle de vie complet d’un objet IMS. Vous apprendrez à **créer, récupérer, mettre à jour et supprimer** un dossier de documents de premier niveau avec les API.
{% stepper %}
{% step %}
### Créer un dossier de documents de premier niveau
Dans l’API, un dossier de documents de premier niveau est un **ensemble**. Sa création exige trois champs :
* **ID du nœud parent** : environnement dans lequel le dossier sera créé.
* *(Pour les dossiers de deuxième niveau ou plus, le parent est l’ID du dossier supérieur.)*
* **Type de nœud** : utilisez `"DOCUMENT_SET"` pour un dossier de premier niveau.
* **Nom** : choisissez un nom pour votre nouveau dossier.
**Point de terminaison :** `POST http://myims.interfacing.com/api/v1/items`
**Exemples de requête et de réponse :**
```json
15:35:11.219 request:
1 > POST http://myims.interfacing.com/api/v1/items?draft=true
1 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
1 > Content-Type: application/json; charset=UTF-8
1 > Content-Length: 139
1 > Host: myims.interfacing.com
1 > Connection: Keep-Alive
1 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
1 > Accept-Encoding: gzip,deflate
{
"parent": {
"nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
},
"@type": "NodeElement",
"name": "my first document set",
"nodeType": "DOCUMENT_SET"
}
```
```json
15:35:11.276 response time in milliseconds: 57
1 < 200
1 < Server: nginx/1.21.6
1 < Date: Wed, 08 Jun 2022 19:35:11 GMT
1 < Content-Type: application/json
1 < Content-Length: 526
1 < X-Varnish: 198276
1 < Age: 0
1 < Via: 1.1 varnish (Varnish/7.1)
1 < Connection: keep-alive
{
"nodeSubTypeName": null,
"userNodeSubType": null,
"@type": "BaseElement",
"nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
"nodeType": "DOCUMENT_SET",
"creationDate": "2022-06-08T15:35:11.253-04:00",
"nodeStatus": "IN_PROGRESS",
"publishedNodeVersionId": null,
"version": "0.0001",
"nodeSubType": null,
"modificationDate": "2022-06-08T15:35:11.253-04:00",
"extensions": null,
"deleted": false,
"system": false,
"referenceNumber": null,
"name": "my first document set",
"locked": false,
"nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
"favorite": false
}
```
**Exemple CURL :**
```bash
curl --request POST --url 'http://myims.interfacing.com/api/v1/items?draft=true' --header 'Content-Type: application/json' -b /tmp/cookie.tmp \
--data '{
"parent": {
"nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
},
"@type": "NodeElement",
"name": "my first document set",
"nodeType": "DOCUMENT_SET"
}'
```
Après l’envoi de la requête, la réponse contient des métadonnées comme `nodeId` et `nodeVersionId`. Vous en aurez besoin pour une mise à jour ou une suppression.
{% endstep %}
{% step %}
### Récupérer un dossier de documents de premier niveau
Pour récupérer un dossier existant de premier niveau, envoyez une requête GET avec son `nodeId`.
**Point de terminaison :** `GET http://myims.interfacing.com/api/v1/items/{nodeId}?draft=true`
**Exemples de requête et de réponse :**
```json
15:35:11.279 request:
2 > GET http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true
2 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
2 > Host: myims.interfacing.com
2 > Connection: Keep-Alive
2 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
2 > Accept-Encoding: gzip,deflate
```
```json
15:35:11.351 response time in milliseconds: 71
2 < 200
2 < Server: nginx/1.21.6
2 < Date: Wed, 08 Jun 2022 19:35:11 GMT
2 < Content-Type: application/json
2 < Content-Length: 526
2 < ETag: W/"06DE9CB7-1E56-49D1-A373-00DFAA8C1C1A|2022-06-08 19:35:11.26"
2 < Cache-Control: no-cache, no-transform, private
2 < X-Varnish: 819211
2 < Age: 0
2 < Via: 1.1 varnish (Varnish/7.1)
2 < Connection: keep-alive
{
"nodeSubTypeName": null,
"userNodeSubType": null,
"@type": "BaseElement",
"nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
"nodeType": "DOCUMENT_SET",
"creationDate": "2022-06-08T15:35:11.253-04:00",
"nodeStatus": "IN_PROGRESS",
"publishedNodeVersionId": null,
"version": "0.0001",
"nodeSubType": null,
"modificationDate": "2022-06-08T15:35:11.253-04:00",
"extensions": null,
"deleted": false,
"system": false,
"referenceNumber": null,
"name": "my first document set",
"locked": false,
"nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
"favorite": false
}
```
**Exemple CURL :**
```bash
curl --request GET --url 'http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true' -b /tmp/cookie.tmp
```
La réponse renvoie tous les détails de l’ensemble de documents, comme lors de sa création.
{% endstep %}
{% step %}
### Mettre à jour un ensemble de documents de premier niveau
Pour effectuer une mise à jour, envoyez la structure complète de l’objet mis à jour, avec :
* le `nodeId` ;
* le `nodeVersionId` actuel ;
* les modifications souhaitées, comme un nouveau nom.
**Point de terminaison :**`PUT http://myims.interfacing.com/api/v1/items/[nodeId]`
**Exemples de requête et de réponse :**
```json
15:35:11.354 request:
3 > PUT http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true
3 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
3 > Content-Type: application/json; charset=UTF-8
3 > Content-Length: 229
3 > Host: myims.interfacing.com
3 > Connection: Keep-Alive
3 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
3 > Accept-Encoding: gzip,deflate
{
"parent": {
"nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
},
"@type": "NodeElement",
"nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
"name": "new name",
"nodeType": "DOCUMENT_SET",
"nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B"
}
```
```json
15:35:11.440 response time in milliseconds: 86
3 < 200
3 < Server: nginx/1.21.6
3 < Date: Wed, 08 Jun 2022 19:35:11 GMT
3 < Content-Type: application/json
3 < Content-Length: 513
3 < X-Varnish: 198279
3 < Age: 0
3 < Via: 1.1 varnish (Varnish/7.1)
3 < Connection: keep-alive
{
"nodeSubTypeName": null,
"userNodeSubType": null,
"@type": "BaseElement",
"nodeVersionId": "BFA4C9F0-89C6-46C1-BD93-7CE15988BF5C",
"nodeType": "DOCUMENT_SET",
"creationDate": "2022-06-08T15:35:11.253-04:00",
"nodeStatus": "IN_PROGRESS",
"publishedNodeVersionId": null,
"version": "0.0002",
"nodeSubType": null,
"modificationDate": "2022-06-08T15:35:11.367-04:00",
"extensions": null,
"deleted": false,
"system": false,
"referenceNumber": null,
"name": "new name",
"locked": false,
"nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
"favorite": false
}
```
**Exemple CURL :**
```bash
curl --request PUT --url 'http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true' --header 'Content-Type: application/json' -b /tmp/cookie.tmp \
--data '{
"parent": {
"nodeId": "A9CCB5F4-9A79-8AE7-8C4C-289A025D0D88"
},
"@type": "NodeElement",
"nodeVersionId": "413426F8-66D4-49F6-843C-2F7AFEB298F5",
"name": "new name",
"nodeType": "DOCUMENT_SET",
"nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B"
}'
```
La réponse contient les métadonnées mises à jour, comme le nouveau `nodeVersionId` et le numéro de version.
{% endstep %}
{% step %}
### Supprimer un dossier de documents de premier niveau
Pour supprimer un ensemble de documents, envoyez une requête DELETE avec le `nodeId` de l’objet dans l’URL. Le corps de la requête doit être vide (`{}`).
**Point de terminaison :** `DELETE http://myims.interfacing.com/api/v1/items/[nodeId]`
**Exemples de requête et de réponse :**
```json
15:35:11.441 request:
4 > DELETE http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true
4 > Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
4 > Content-Type: application/json; charset=UTF-8
4 > Content-Length: 2
4 > Host: myims.interfacing.com
4 > Connection: Keep-Alive
4 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
4 > Accept-Encoding: gzip,deflate
{
}
```
```json
15:35:11.617 response time in milliseconds: 176
4 < 200
4 < Server: nginx/1.21.6
4 < Date: Wed, 08 Jun 2022 19:35:11 GMT
4 < Content-Type: application/json
4 < Content-Length: 514
4 < X-Varnish: 819214
4 < Age: 0
4 < Via: 1.1 varnish (Varnish/7.1)
4 < Connection: keep-alive
[
{
"nodeSubTypeName": null,
"userNodeSubType": null,
"@type": "BaseElement",
"nodeVersionId": "BFA4C9F0-89C6-46C1-BD93-7CE15988BF5C",
"nodeType": "DOCUMENT_SET",
"creationDate": "2022-06-08T15:35:11.253-04:00",
"nodeStatus": "IN_PROGRESS",
"publishedNodeVersionId": null,
"version": "0.0002",
"nodeSubType": null,
"modificationDate": "2022-06-08T15:35:11.500-04:00",
"extensions": null,
"deleted": true,
"system": false,
"referenceNumber": null,
"name": "new name",
"locked": false,
"nodeId": "1450CEF9-89A3-4B48-98F7-09735BECD54B",
"favorite": false
}
```
**Exemple CURL :**
```bash
curl --request DELETE --url 'http://myims.interfacing.com/api/v1/items/1450CEF9-89A3-4B48-98F7-09735BECD54B?draft=true' --header 'Content-Type: application/json' -b /tmp/cookie.tmp \
--data '{}'
```
La réponse confirme la suppression et contient les informations de l’objet.
{% endstep %}
{% endstepper %}
## Voir aussi
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://interfacing.gitbook.io/interfacing-help-files/interfacing-help-files-fr/developpeurs-de-solutions/api-and-information-repository/api-rest.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
