Skip to content

[API] Dossier technique (fr)

Jump to bottom
FPierre edited this page Jul 12, 2016 · 10 revisions

Dossier technique de l'API

I. Présentation de l'API

A. Principe général de fonctionnement

Il a été décidé de centraliser les interactions entre les différents éléments du projet sur une API. Cela permet une distribution des fonctionnalités selon les URLs que les clients de l'API utilisent.

Il s’agit d’une API HTTP standard, mais également d’une API Websocket, qui permet à l’application Web de recevoir des informations du serveur en temps réel.

B. Architecture

  • Framework : Ruby on Rails 5
  • Base de données : MySQL
  • Formats de retours des URLs : JSON
  • Architecture : MVC

C. Librairies et logiciels

Redis

L'implémentation des Websockets dans Ruby en Rails requiert un système de Queue. Il permet de différer de manière asynchrone les appels entre clients et serveur Webscoket.

Redis est une solution technique éprouvée, qui se met en place sans difficulté.

Sidekiq

Pour rappel, le déclenchement d'un Reminder peut être fait selon 2 modes. A la création, si

  1. l'attribut displayed_at est renseigné, le Reminder sera affiché à cette date
  2. l'attribut displayed_at n'est pas renseigné, le Reminder sera affiché immédiatement

Le premier mode requiert un système de déclenchement à un instant donné (displayed_at en l'occurence). Ce système est assuré par le logiciel Sidekiq. Basé sur Redis, il offre une interface de programmation pour permettre le mode de déclenchement.

D. API externes

OpenWeatherMap

L'application Web affiche la météo. Elle est mise à jour toutes les 20 minutes grâce à un CRON système. Ces mises à jour sont communiquées à l'application Web en Websocket, ce qui évite le rechargement de la page.

C'est l'API OpenWeatherMap qui permet de récupérer les informations météorologiques. L'API y accède grâce à la gem open-weather. Elle offre une couche d'abstraction pour consulter facilement l'API.

Twitter

L'API peut suivre de personnes sur Twitter. Lorsqu'une personne suivie tweet, l'API Twitter prévient l'API DOT. Cette dernière est donc en mesure de communiquer le contenu du tweet à l'application Web, en Websocket.

C'est un daemon Ruby qui gère cette reception du tweet et son envoi sur l'application Web.

II. Ressources

La documentation des ressources se trouve également sur l'URL /apipie de l'API.

Diagramme de classes

Lien

A. Raspberry Pi

Méthode Verbe HTTP URL Accès Description
index GET /raspberries Récupère tous les Raspberry Pi
show GET /raspberries/:id Récupère un Raspberry Pi
create POST /raspberries Crée un Raspberry Pi
update PUT/PATCH /raspberries/:id Modifie un Raspberry Pi
destroy DELETE /raspberries/:id Supprime un Raspberry Pi

Format de retour :

{
  "data": {
    "id": "1",
    "type": "raspberries",
    "attributes": {
      "api-port": 8080,
      "created-at": "2016-06-06T21:42:53.000+02:00",
      "domain-name": '42.fr',
      "ip-address": "42.42.42.42",
      "mac-address": "42:42:51:7D:1C:02",
      "master-device": false,
      "name": "Raspberry 1"
    }
  }
}

B. Reminders (mémos)

Méthode Verbe HTTP URL Accès Description
index GET /reminders Utilisateur approuvé ou admin Récupère les 10 derniers Reminders
show GET /reminders/:id Utilisateur approuvé ou admin Récupère un Reminder
create POST /reminders Utilisateur approuvé ou admin Crée un Reminder
destroy DELETE /reminders/:id Utilisateur approuvé ou admin Supprime un Reminder
erase_all DELETE /reminders/erase_all Utilisateur approuvé ou admin Efface les Reminders affichés sur l'écran interne

Format de retour :

{
  "data": {
    "id": "9",
    "type": "reminders",
    "attributes": {
      "content": "Reminder content",
      "created-at": "2016-05-28T15:58:06.000Z",
      "displayed-at": "2016-05-29T00:00:00.000Z",
      "duration": 10,
      "priority": 1,
      "title": "Reminder for test",
      "type": "alert",
      "user": "Pierre Flauder",
      "displayed": false,
      "displayed-ago": "environ 9 heures"
    }
  }
}

C. Screens (écrans)

Méthode Verbe HTTP URL Accès Description
path GET /screens/path/from/:from/to/:to Affiche le chemin entre 2 villes

D. Settings (paramètre)

Méthode Verbe HTTP URL Accès Description
show GET /settings/:id Récupère l'objet Setting
update PUT/PATCH /settings/:id Utilisateur approuvé ou admin Modifie l'objet Setting

Format de retour :

{
  "data": {
    "id": "1",
    "type": "settings",
    "attributes": {
      "reminders-enabled": false,
      "room-occupied": false,
      "sarah-enabled": false,
      "screen-guest-enabled": false,
      "twitter-enabled": false
    }
  }
}

E. Registration (enregistrement)

Méthode Verbe HTTP URL Accès Description
create POST /users Crée un User

F. Session (User)

Méthode Verbe HTTP URL Accès Description
create POST /users/sign_in Connecte un User

G. Test

Méthode Verbe HTTP URL Accès Description
ping GET /tests/ping Utilisateur approuvé ou admin Récupère le statut de l'API
voice POST /tests/voice Utilisateur approuvé ou admin Envoi du texte que SARAH répète

H. User (utilisateur)

Méthode Verbe HTTP URL Accès Description
index GET /users Utilisateur approuvé ou admin Récupère tous les Users
show GET /users/:id Utilisateur approuvé ou admin Récupère un User
update PUT/PATCH /users/:id Utilisateur approuvé ou admin Modifie un User
destroy DELETE /users/:id Utilisateur admin Supprime un User

I. Voice command (commande vocale)

Méthode Verbe HTTP URL Accès Description
index GET /voice_commands Récupère toutes les commandes vocales disponibles pour SARAH

J. Voice recognition server (serveur de reconnaissance vocale)

Méthode Verbe HTTP URL Description
show GET /voice_recognition_servers/:id Récupère l'objet du serveur de reconnaissance vocale
update PUT/PATCH /voice_recognition_servers/:id Modifie l'objet du serveur de reconnaissance vocale

Format de retour :

{
  "data": {
    "id": "1",
    "type": "voice_recognition_servers",
    "attributes": {
      "api_port": nil,
      "domain_name": nil,
      "ip_address": nil,
      "mac_address": nil
    }
  }
}

K. Weather (météo)

Méthode Verbe HTTP URL Accès Description
show GET /weather Récupère les informations météorologiques de la ville de Paris

Format de retour :

{
  data: {
    "weather": "sunshine",
    "temp": {
      "current": "22",
      "min": "12",
      "max": "23"
    }
  }
}
Clone this wiki locally