Dernière màj le 21/02/2014 par A.T.
Readme non à jour, préférez le guide d'utilisation Eggstar si disponible.
- La création de cette API a grandement été aidée par l'article suivant: Creating a RESTful API with PHP- J'ai par ailleurs repris certains standards fournis par la Maison Blanche: WhiteHouse API Standards
- L'ensemble des échanges se fait dans cette v1 de l'API uniquement en JSON.
- Cette v1 de l'API n'incluera que ce dont nous sommes sûrs que le client mobile Sunbeam a besoin de requêter pour son bon fonctionnement. Les endpoint sont des noms au pluriel, tel que users.
Pour certaines requêtes, une clé d'API sera demandée. Cette clé est un GUID créée à l'inscription de l'utilisateur. L'URL d'une requête GET ressemble à ceci: http://localhost/eggstar/v1/users
Ici, s'il y a dans le endpoint users un retour de GET de prévu, on devrait récupérer l'intégralité des utilisateurs.
Exemple de requête qui retournerait quelque chose puisque implémenté (au 21/02/2014):
GET http://localhost/eggstar/v1/users?email=toto@toto.com&password=zfije5rçf_heofuhf
Il s'agit d'une requête type de demande d'authentification d'utilisateur. Le mot de passe doit être envoyé chiffré (sha1 d'un md5 du mot de passe). La présente requête renvoie une erreur ou les informations de l'utilisateur s'il a été trouvé. Pour les requêtes de type PUT, il est demandé d'envoyer les données dans le "request body".
Pour inscrire un nouvel utilisateur, notre requête serait: PUT http://localhost/eggstar/v1/users avec en request body ceci:
{"name":"nom","firstName":"prénom","email":"adresse e-mail","password":"mot de passe"} La gestion des erreurs est intégrée à l'API. Une erreur est renvoyée en JSON sous la forme {'error':'message d'erreur user-friendly'}. Ce message d'erreur est plutôt destiné au développeur qui utilise l'API dans son application. De fait certaines informations (ID par exemple) peuvent se trouver dans ces messages pour une meilleure "traçabilité". PhpStorm dispose d'un client REST intégré qui se trouve dans Tools > Test RESTful Web Service.
Dans le cas du PUT, nous parlions plus tôt de mettre les données dans le "request body". Dans PhpStorm, sous request body, cochez "Text:" et tapez votre JSON ici. Lien de téléchargement: cliquez ICI. Dans le cas du PUT, pour mettre des données dans le request body, il faut choisir "raw" et "JSON" dans le choix du type (sorte de menu déroulant).