laposte-okapi-sdk
v0.0.6
Published
La Poste Open API client SDK for JavaScript / nodejs / browsers
Downloads
4
Readme
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)