Le SDK client Okapi pour JavaScript / nodejs / navigateurs

Ce SDK facilite la consommation des Open APIs de La Poste, via la plateforme Okapi :

Pour consommer des APIs de La Poste, vous devez au préalable :

• Créer votre compte
• Créer une application et noter la clé d'app générée, à utiliser comme appKey dans le SDK
• Souscrire à une API du store

Installation

$ npm i laposte-okapi-sdk --save

Utilisation

constokapiSdk=require('laposte-okapi-sdk');constoka=okapiSdk({appKey: 'mySecretAppKey'});oka.api('superapi').version(1).resource('contacts').get().spread((data,res)=>{console.log('data :',data);console.log('status code :',res.statusCode);}).catch(function(err){console.error(err);});

La méthode verbe déclenche la requête avec la l'équivalent HTTP de get, post, put, patch ou delete.

Tous les exemples suivants sont équivalents :

• chainage :

  oka.api('superapi').version(1).resource('contacts').get()

• la méthode verbe accepte une chaîne de caractère comme chemin de la ressource :

  oka.api('superapi').version(1).get('contacts')

• la méthode verbe considère le paramètre comme l'URL complète s'il est du type String et qu'aucune API n'a été renseignée au préalable :

  oka.get('superapi/v1/contacts')

• construction directe via un objet :

  oka.build({api: 'superapi',version: 1,resource: 'contacts'}).get()

• encore plus direct via la méthode verbe :

  oka.get({api: 'superapi',version: 1,resource: 'contacts'})

Utilisation dans un navigateur

Après installation via NPM

• Version adaptée à la production :

  <scriptsrc="node_modules/laposte-okapi-sdk/client/okapi-sdk.min.js"></script>

• Version non minifiée pour les développements :

  <scriptsrc="node_modules/laposte-okapi-sdk/client/okapi-sdk.js"></script>

Directement

• Version adaptée à la production :

  <scriptsrc="https://github.com/DeveloperLaPoste/okapi-sdk-js/raw/master/client/okapi-sdk.min.js"></script>

• Version non minifiée pour les développements :

  <scriptsrc="https://github.com/DeveloperLaPoste/okapi-sdk-js/raw/master/client/okapi-sdk.js"></script>

Référence API

Les méthodes suivantes peuvent être chainées : elles retournent this (Object) pour permettre un chainage des appels.

.api

Définit le contexte d'URL de l'API à consommer.

Arguments : contexte d'URL de l'API (String)

.version

Définit la version de l'API à consommer.

Arguments : version (Integer|String)

.resource

Définit l'URI de ressource de l'API à consommer.

Arguments : URI de la ressource (String)

.uri

Définit une URI complète à utiliser (alternative à l'utilisation de .api et .version).

Arguments : uri (String) (ex : '/APIname/APIversion/resource')

.body

Définit le corps de la requête.

Arguments : corps (Object)

.query

Définit les paramètres de query string.

Arguments: query (Object)

.params

Défnit les paramètres de l'URI.

Arguments: params (Object)

.attachment

Définit un fichier à uploader.

Arguments: attachment (Object)

.build

Méthode utilitaire tout-en-un qui construit l'URI.

Arguments: opt (Object)

Exemple :

{API name, API version, resource, [...]})

Les méthodes suivantes ne sont pas chainées :

.toUrl

Retourne l'URL complète de la requête.

Arguments: [opt] (Object)

Exemple :

{API name, API version, resource, [...]}

Retourne une URL complète (String)

.get | .post | .put | .patch | .post | .delete

Ces méthodes sont identiques à leur équivalent HTTP, l'invocation de l'une de ces méthode déclenche l'appel de la requête au serveur.

Arguments: [opt] (Object)

Exemple :

{API name, API version, resource, [...]}

Retourne une promesse qui se réalise avec les arguments suivants :

• res : réponse (Object)
• body : corps de la réponse body (Object)