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

  const okapiSdk = require('laposte-okapi-sdk');
  const oka = 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 :

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

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

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

Directement

• Version adaptée à la production :

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

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

  <script src="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)