Propriétés de Navigation

Présentation

Les propriétés de navigation permettent de définir les relations entre les différentes ressources. C’est donc par le biais de ces propriétés qu’il sera possible d’associer une écriture à un journal, un compte général, etc. ou encore associer un compte principal et une devise à un client.

Ces relations peuvent être de deux natures :

• soit une relation simple vers une ressource,
• soit une relation vers une collection de ressources.

Relation simple (single-valued navigation)

Ce type de relation correspond aux relations de type 1..1 et 1..?.

Certaines propriétés sont identifiées dans le manuel de référence de l’API par un type single-value navigation. Ce type indique que la propriété est en lien unique avec une ressource.

Relation avec une collection (collection-valued navigation)

Il s’agit d’une relation de type 1..+ ou 1..*

Manipulation des relations

Les méthodes de sélection, affectation ou de suppression des relations diffèrent suivant la nature de la relation.

Cependant, quel que soit le type de relation, pour les opérations d’affectation (POST, PUT et PATCH), la valeur qui devra être affectée à la propriété de relation correspondra toujours au lien de référence de la ressource à associer.

Ce lien de référence correspond à l’url permettant d’accéder directement à une ressource, elle est codifiée de la manière suivante : {url API}/{datasetId}/{ressource}(‘{id ressource}’)

Relation simple

Lecture

D’une manière générale, pour toutes les propriétés de relation, une route spécifique permettant d’accéder aux données est publiée.

{url API}/{datasetId}/clients('{id client}')/comptePrincipal

Il existe cependant une autre méthode permettant de récupérer ces données. Elle consiste à utiliser le paramètre $expand dans la route de la ressource parente de la propriété de relation.
Le résultat retournera le détail des informations de la ressource parente (clients dans notre exemple), avec en plus le détail de la ressource associée (comptePrincipal dans notre exemple).

{url API}/{datasetId}/clients('{id client}')?$expand=comptePrincipal

Enfin, il existe une route permettant de récupérer directement l’url de référence de la propriété de relation. Celle-ci se termine avec l’extension $ref.

{url API}/{datasetId}/clients('{id client}')/comptePrincipal/$ref

Affectation

Sur les propriétés permettant une relation simple, pour exécuter des opérations d’ajout ou modification de données (POST, PUT ou PATCH), il faudra affecter l’url de référence en utilisant la syntaxe :
propriété@odata.bind à affecter avec l’url de référence de la ressource à associer.

Création

Lors de la création, les propriétés permettant une relation simple seront à affecter au même niveau que les autres propriétés.

{url API}/{datasetId}/clients
{
    "sommeil": false,
    "commentaire": "",
    "siret": "",
    "identifiant": "FR373087844356",
    "ape": "95.25Z",
    "contact": "Jean-claude BERTAU",
    "classement": "Bertau S.a.r.l",
    "qualite": "Société",
    "intitule": "Client Bertau",
    "type": "Client",
    "numero": "BERTAU",
    "encoursMaximum": 100000.0,
    "nonSoumisPenalites": false,
    "modeCtrlEncours": "Automatique",
    "adresse": {
        "complement": "BP 14",
        "codePostal": "44000",
        "adresse": "144, route de la soie",
        "ville": "NANTES",
        "codeRegion": "",
        "pays": "France"
    },
    "telecom": {
        "telephone": "02 40 48 67 95",
        "telecopie": "02 40 48 67 90",
        "eMail": "",
        "site": ""
    },
    "[email protected]": "{url API}/{datasetId}/comptes('{id compte}')",
    "[email protected]": "{url API}/{datasetId}/devises('{id devise}')"
}

Modification

Pour modifier une propriété de relation, comme pour le cas du POST, il faudra utiliser la syntaxe propriété@odata.bind.

{url API}/{datasetId}/clients('id client')
{
    "commentaire": "Client à contacter",
    "[email protected]":"{url API}/{datasetId}/comptes('{id compte}')"
}

Suppression

La suppression d’une relation simple n’est possible que pour les propriétés de relation de type 1..?.
Comme pour les routes permettant la sélection, il existe une route spécifique permettant de supprimer la relation. Ces routes sont de type DELETE et se terminent par l’extension $ref.

{url API}/{datasetId}/clients('{id client}')/devise/$ref

Relation avec une collection de ressources

Lecture

Pour les propriétés de relation avec une collection de ressources, il existe deux types de route de sélection :

• La première permet de récupérer directement les données de chaque ressource (équivalent à un $expand).
• La deuxième se terminant par l’extension $ref, permet quant à elle de récupérer les url de référence des ressources associées.

{url API}/{datasetId}/clients('{id client}')/comptes

"@odata.context": "{url API}/{datasetId}/$metadata#comptes",
"value": [
    {
        "sommeil": false,
        "optDevise": true,
        "optTiers": true,
        "optEcheance": true,
        "report": "Detail",
        "classement": "Collectif clients",
        "intitule": "Collectif clients",
        "type": "Detail",
        "numero": "4110000",
        "dateModification": "2020-02-03T00:00:00Z",
        "dateCreation": "2020-04-08T09:00:11Z",
        "id": "{id compte 411000}"
    },
    {
        "sommeil": false,
        "optDevise": true,
        "optTiers": true,
        "optEcheance": true,
        "report": "Detail",
        "classement": "Collectif client-",
        "intitule": "Collectif client-effets à recevoir",
        "type": "Detail",
        "numero": "4130000",
        "dateModification": "2019-02-05T00:00:00Z",
        "dateCreation": "2020-04-08T09:00:11Z",
        "id": "{id compte 413000}"
    }
]
}

{url API}/{datasetId}/clients('{id client}')/comptes/$ref

{
    "@odata.context": "{url API}/{datasetId}/$metadata#Collection($ref)",
    "value": [
        {
            "@odata.id": "{url API}/{datasetId}/comptes('{id compte 4110000}')"
        },
        {
            "@odata.id": "{url API}/{datasetId}/comptes('{id compte 4130000}')"
        }
    ]
}

Affectation

Ce type de collection ne peut contenir qu’une liste de ressources existantes (ressources comptes par exemple).

Ainsi il n’est pas possible de modifier directement ce type de ressource dans la collection de relations. Il n’existe donc pas de requête PUT ou PATCH pour ce type de propriété.

De la même manière, l’ajout d’un élément dans la collection permet d’ajouter un lien de référence vers une ressource existante, ça ne permet donc pas de créer une nouvelle ressource.

• Pour ajouter un nouveau compte général dans la base, il faudra utiliser une requête POST sur la ressource comptes.
• Pour ajouter une relation dans la collection (requête de type POST), il faudra spécifier l’url de référence de la ressource à ajouter dans la collection en utilisant la syntaxe @odata.id. Les routes permettant d’ajouter un élément à une collection de ressources se terminent par l’extension $ref.

{url API}/{datasetId}/clients('{id client}')/comptes/$ref
{
  "@odata.id":"{url API}/{datasetId}/comptes({id compte})"
}

Suppression

Pour supprimer un élément dans la collection (requête de type DELETE), il faudra spécifier l’url de référence de l’élément à supprimer dans la collection.
Pour ce faire, il faudra également utiliser la syntaxe : @odata.id

{url API}/{datasetId}/clients('{id client}')/comptes/$ref
{
  "@odata.id":"{url API}/{datasetId}/comptes({id compte})"
}