Blogue

API PHPR V3

Pourquoi un API ?

Dans le but de d’augmenter votre performance par l’automatisation, La suite logiciels de gestion PHPReaction vous offre sont APIv3

Celle-ci permettra de remplacer le travail manuel, le besoin de papier / support physique et service IDE (Electronic Data Interchange)

Il s’agit d’une façon moderne d’interagir entre plusieurs applications et outils de votre choix (interopabilité ).

Effectivement, celle-ci vous permet d’accéder à toutes vos données en temps réel.

 

PHPReaction vous offre un API (« Application Programming Interface » )

Plus précisément un API web de type REST  / RESTful – Web Services

 

API-Platform  ont faites leur preuve depuis 2015. La plateforme est conçu de technologies Open Source  supporté par plus de 3000 développeur et utilise des standard reconnu du domaine TI.

Une approche OOP (« Object Oriented Programming » ) SOLID  & CRUD  qui permet d’accéder à plusieurs fonctionnalités de type :

  • Lecture de liste et détail via « GET Method »
  • Ajout / Création via « POST Method »
  • Modification via « PUT Method »
  • Effacement via « DELETE Method »

 

Celle-ci communique en sérialisation « JSON »  ( Exemple ici ) spécifiquement « JSON-LD » 

Directement sur mon projet / Base URL

La documentation va faire référence à tout moment à votre projet en tant que « xxx.phpreaction.com »

« xxx.phpreaction.com » doit être remplacer par votre lien de projet.

Vous utilisez celui-ci à chacune des connexions à PHPReaction.

Par exemples :

« xxx.phpreaction.com » => « artisansdazures.phpreaction.com »

« xxx.phpreaction.com » => « picardmarine.phpreaction.com »

 

Si vous désirez ne pas travailler sur une version « Live »/ »Production »/ »Réel », il est possible de vous fournir une version « Sandbox »/ »Demo »/ »Staging » pour votre développement.

Simplement contacter votre administrateur PHPReaction

Utilisation de l'API via URL HTTP

Il est très simple d’utilisé l’API PHPReaction puiqu’il s’agit d’URL HTTP … donc de lien internet « web address ». Par exemple : https://www.google.com

Par besoin de logiciel ou outil spécialisé.

 

Donc à tout moment, vous pouvez copier un lien en texte et le collé dans votre barre de navigation « address bar »  de votre fureteur internet « web browser » . Notre navigateur de préférence est « Google Chrome Web Browser » 

Bien entendu, certaine extension peuvent être pertinent pour les utilisateurs les plus intensifs.

  • JSON formater  ou directement en extention Chrome pour l’affichage & navigation des réponses JSON
  • PostMan  pour découvrir / apprendre / tester l’API 

 

Pour les utilisateurs plus avancé ou les administrateurs de système vous pourrez utiliser l’outil de votre choix comme CURL ou autre CLI

Authentification

Communiquer avec l'API

Vous devez toujours obtenir une clé d’accès temporaire* (« access token » )

Il s’agit d’une suite de chiffre et lettre minuscule et majuscule d’environ 85 caractères

Ex : MTcyNWNjM2JjMzNmMTI3NzNiNzFiYjk1YmQxNDEwNGQ5ODdlNDgzOWE1MzMwNzFmYmU4NjNmN2u0NWVlZmNiZ1

 

Suite à l’obtention de votre clé / « access token », vous pourrez l’utilisé sur des ressources spécifiques ( Voir la section « Ressources »)

Obtenir une clé d'API / Access Token

Il y a 3 méthodes d’obtenir une clé

  1. Déjà avoir une clé valide
  2. Récupérer une clé manuellement (Ci-dessous)
  3. Récupérer une clé par authentification (Ci-dessous)

* Le délais d’expiration « TTL » de votre clé / « token » est selon les configurations du projet. Celle-ci sera de 1h jusqu’à 24h maximum

Lors qu’elle est expiré, simplement en prendre une nouvelle.

 

Suite à l’obtention de la clé d’accès, utilisé celle-ci

  1. Ajoutez le comme paramètre de la requête au nom de « access_token »

Exemple :

http://xxx.phpreaction.com/platform/v3/products?access_token=ZDE3OTdmYjY2ODFiNTE1ZjI3Yjc0Z

Autoriser l'application manuellement

  1. Connectez-vous à l’application de gestion PHPReaction
  2. Aller à votre profil d’utilisateur
    • Le lien du profil se trouve sur votre nomme d’utilisateur dans le coin supérieur droit (https://xxx.phpreaction.com/profile/)
  3. Cliquer sur « Générer une clé d’accès » / « generateAccessToken »
    • (Comme toutes fonctionnalité du système, il est possible que vous n’ayez pas les droits requis)
  4. Vous devriez alors voir les informations d’autentification temporaire : « accessToken » et « accessTokenExpireAt »

Autoriser l'application automatiquement

  1. Demander les credentials OAuth  de client OAuth2  (client_id // client_secret) auprès de votre administrateur PHPReaction
  2. Obtenir les identifiants (Username // Password) PHPReaction de votre utilisateur
  3. Envoyer une requête à l’url d’authorization (/oauth/v2/token) afin de recevoir un « access_token »

Exemple :

 http://xxx.phpreaction.com/oauth/v2/token?
grant_type=password
&client_id=3_4wqfwqwys54wgw0gg0c
&client_secret=15sf0mu8fj7k0skw4w0w
&username=thisUser
&password=thisSecretPassword
&redirect_uri=/

4. Il est possible d’obtenir une réponse de non-autorisation

{
    "error""unauthorized_client",
    "error_description""The grant type is unauthorized for this client_id"
}

Vous n’utilisez simplement pas la bonne clé ou quelle n’est pas inscrite parfaitement.

Ressources

Par la liste des ressources vous trouverez :

  • l’ensemble des entités accessible par l’API
  • Chacune des façons possible des l’appeler « Call »
    • Lecture : GET
    • Ajouter : POST
    • Modifier : PUT
    • Effacer : DELETE
  • La structure descriptive / informations des propriétés dans la section « Models »

 

Si vous ne trouvez par ce que vous rechercher, il est possible que votre utilisateur ne soit pas autorisé au niveau de ses droits d’accès.

Listes des ressources de l'API

Pour accèder la à liste vous devez utiliser votre clé d’accès / « Access Token » / « access_token »

https://xxx.phpreaction.com/platform/v3?access_token=ACCESS_TOKEN

 

Si vous n’avez pas de clé / « Access Token » simplement vous référer à la section « Authentification »

Listing

Objectif: Afficher la liste de toutes les entités avec la possibilité d’appliquer des filtres et paginations.

Description: Fait la liste des toutes les entités en fonction des filtres appliqués. Affiche des informations limités selon l’entité.

HTTP Method: GET

Request URI:

Pattern: {baseUrl}/platform/v3/{plurializedEntityName}

Exemple: xxx.phpreaction.com/platform/v3/products

Response status:

200: Resource collection response

Show

Objectif: Afficher tous les champs d’une entité spécifique.

Description: Fait la liste de toutes les propriétés du produit demandé, puis les affiche en ajoutant des liens hypermedia sur les relations.

HTTP Method: GET

Request URI:

Pattern: {baseUrl}/platform/v3/{plurializedEntityName}/{id}

Exemple: xxx.phpreaction.com/platform/v3/products/4

Response status:

200: Resource item response

Get Relations

Objectif: Récupérer les relations one-to-many d’une entité afin de préparer la suppression avec transfert de relations.

Description: Retourne une liste d’hypermedia link des relations affectés par la suppression de l’entité. Ne supprime pas directement l’entité.

HTTP Method: GET

Request URI:

Pattern: {baseUrl}/platform/v3/{plurializedEntityName}/get_delete_relations/{id}

Exemple: xxx.phpreaction.com/platform/v3/products/get_delete_relations/4

Response status:

200: Resource deleted

Simple List

Objectif: Affiche une liste de toutes les entités pour utiliser dans un formulaire de choix / Dropdown .

Description: N’affiche que le nom de l’entité ainsi que son ID.

HTTP Method: GET

Request URI:

Pattern: {baseUrl}/platform/v3/{plurializedEntityName}/simple_list

Exemple: xxx.phpreaction.com/platform/v3/products/simple_list

Response status:

200: Resource deleted

Create

Objectif: Créer une nouvelle entité.

Description: Permet de créer une entité en passant les champs dans un format JSON.

HTTP Method: POST

Request URI:

Pattern: {baseUrl}/platform/v3/{plurializedEntityName}

Exemple: xxx.phpreaction.com/platform/v3/products

Sending:

Data type: JSON

Content: Toutes les propriétés requises + les propriétés désirées

Exemple:

 {
  "weight""10",
  "dimensionW""1",
  "dimensionH""1",
  "dimensionD""1",
  "cost""1",
  "invQtyMin""1",
  "invQtyMax""5",
  "moq""2",
  "packageOrder""2",
  "inventoryTracking"true,
  "rentTracking"true,
  "countedInInventory"true,
  "taxable"true,
  "price""5",
  "sku""GooGooGaaGaa",
  "type""/platform/v3/product_types/1",
  "supplier""/platform/v3/suppliers/1",
  "visibleStatus"true,
  "newStatus"true,
  "shippingTracking"true,
  "unitType""/platform/v3/unit_types/1",
  "bookable"true,
  "salable"true,
  "purchasable"true,
  "onDistribution"true,
  "onWebsite"true,
  "discountable"true,
  "isVariableExpense"true,
  "isImmo"true,
  "producible"true,
  "createdAt""2018-07-12T20:58:44.290Z",
  "updatedAt""2018-07-12T20:58:44.290Z"
}

Response status:

200: Resource created

 

Erreurs possibles:

"hydra:description""Update is not allowed for this operation."

Fix : Il y a un ID dans la requête. On ne peut pas forcé l’ID lors de la création d’une entitée.

 

"hydra:description""The type of the \"price\" attribute must be \"string\", \"double\" given."

Fix : Les valeurs de type Float et Double doivent être envoyé comme des String pour garder le niveau de précision. Ex: « amount »: « 5.5 »

Update

Objectif: Modifier les informations d’une entité.

Description: Permet de modifier spécifiquement les informations fournies d’une entité par son ID en passant les champs dans un format JSON.

HTTP Method: PUT

Request URI:

Pattern: {baseUrl}/platform/v3/{plurializedEntityName}/{id}

Exemple: xxx.phpreaction.com/platform/v3/products/4

Sending:

Data type: JSON

Content: Properties to update

Exemple:

{
  "sku""Jo-Blo"
}

Response status:

200: Resource updated

 

Erreurs possibles:

"hydra:description""Update is not allowed for this operation."

Fix : Il n’y a pas de ID dans la requête. On ne peut pas ciblé l’ID pour la mise à jour d’une entitée.

 

"hydra:description""The type of the \"price\" attribute must be \"string\", \"double\" given."

Fix : Les valeurs de type Float et Double doivent être envoyées comme des String pour garder le niveau de précision. Ex: « amount »: « 5.5 »

Objectif: Supprimer l’entité.

Description: Permet de supprimer une entité en applicant le self-deletable s’il y a lieu.

HTTP Method: DELETE

Request URI:

Pattern: {baseUrl}/platform/v3/{plurializedEntityName}/{id}

Exemple: phpc.phpreaction/platform/v3/products/4

Response status:

200: Resource deleted