Présentation de l'API REST

Qu'est-ce-qu'une API REST ?

REST (representational state transfer) est un style d'architecture logicielle définissant un ensemble de contraintes à utiliser pour créer des services web. Les services web conformes au style d'architecture REST, aussi appelés services web RESTful, établissent une interopérabilité entre les ordinateurs sur Internet. Les services web REST permettent aux systèmes effectuant des requêtes de manipuler des ressources web via leurs représentations textuelles à travers un ensemble d'opérations uniformes et prédéfinies sans état.

— Contributeurs de Wikipédia, l'encyclopédie libre et gratuite

Intérêt de l'API REST ?

L'API REST d'Opencomp vous permet d'effectuer des actions automatisées sans avoir besoin d'utiliser manuellement l'application (par l'entremise d'un navigateur Web).

L'API peut, par exemple, permettre à un programme de récupérer des données depuis Opencomp (par exemple les élèves de vos classes, vos évaluations, etc.) mais également d'en envoyer (résultats obtenus aux évaluations par exemple).

Authentification

L'API REST est sécurisée et vous n'avez bien sûr accès qu'aux données concernant vos classes.

Afin de vous authentifier, vous devez passer le paramètre d'URL api_key avec pour valeur votre clé d'API personnelle accessible depuis la rubrique Mon compte de l'application.

Formats de retour

Le format de retour est toujours spécifié en fin d'URL.

Les formats de retour possibles sont :

JSON

JavaScript Object Notation (JSON) est un format de données textuelles dérivé de la notation des objets du langage JavaScript. Il permet de représenter de l’information structurée.

Un document JSON a pour fonction de représenter de l'information accompagnée d'étiquettes permettant d'en interpréter les divers éléments, sans aucune restriction sur le nombre de celles-ci.

Un document JSON ne comprend que deux types d'éléments structurels :

• des ensembles de paires « nom » (alias « clé ») / « valeur » ;

• des listes ordonnées de valeurs.

Ces mêmes éléments représentent trois types de données :

• des objets ;

• des tableaux ;

• des valeurs génériques de type tableau, objet, booléen, nombre, chaîne ou null.

— Contributeurs de Wikipédia, l'encyclopédie libre et gratuite

XML

L'Extensible Markup Language, généralement appelé XML, « langage de balisage extensible » en français, est un métalangage informatique de balisage générique qui dérive du SGML. Sa syntaxe est dite « extensible » car elle permet de définir différents espaces de noms, c'est-à-dire des langages avec chacun leur vocabulaire et leur grammaire, comme XHTML, XSLT, RSS, SVG… Elle est reconnaissable par son usage des chevrons (<, >) encadrant les noms des balises. L'objectif initial de XML est de faciliter l'échange automatisé de contenus complexes (arbres, texte enrichi, etc.) entre systèmes d'informations hétérogènes (interopérabilité).

— Contributeurs de Wikipédia, l'encyclopédie libre et gratuite

Pagination des résultats

Lorsque l'API REST renvoie un ensemble de résultats (listing), les résultats sont paginés. Dans ce cas, les informations de pagination telles que le nombre total de résultats, le nombre de résultats par page et la quantité de pages sont indiqués dans le tableau portant la clé paging.

Exemple JSON

{
     "paging": {
         "count":38916,
         "perPage":30,
         "pageCount":1298
     },
     "objects": [{...},{...},{...}, ...]
 }

Exemple XML

<response>
    <paging>
        <count>38916</count>
        <perPage>30</perPage>
        <pageCount>1298</pageCount>
    </paging>
    <objects>...</objects>
    <objects>...</objects>
    <objects>...</objects>
</response>

Points de terminaison

Nomenclatures

Classes