Web Services: exemple Escacs

De Cacauet Wiki
Salta a la navegació Salta a la cerca

Article anterior: Web Services

Objectius

Proposem un exercici amb web services. Volem fer un joc d'escacs disponible per diversos clients (aplicació browser desktop, aplicació mòbil, etc.)

En l'anterior article Web Services es proposa treballar amb MongoDB i utilitzar el framework CherryPy. Fes-li un cop d'ull per veure exemple pertinent.

Passem a especificar les diverses funcions que necessitem per implementar el WS:


Objectes del servei

Els objectes de més alt nivell (usuaris, partides) corresponen a les col·leccions de MongoDB.

  • Usuari:
    • uid
    • Nick
    • email
    • estat
  • Partida:
    • pid
    • jugador_blanques: uid
    • jugador_negres: uid
    • fitxes: [] array amb les diverses peces del taulell i les seves posicions
      • { color:'b', tipus:'peo', fila:2, col:3 }
      • ...
  • torn: nº de torn (parells=mou blanca, senars=mou negra)
  • inici: data + hora d'inici de partida (timestamp)


Especificació

API
Endpoint IN (GET o POST+JSON) OUT (JSON)
/partida pid: id de partida (GET) status: ok/error
msg: detalls del error
partida: totes les dades de la partida
/en_espera status: ok/error
msg: detalls del error
usuaris: [] array d'usuaris en espera
/juga uid_adversari: uid de la persona amb qui ens volem enfrontar
uid_usuari: la nostra uid
status: ok/error
msg: detalls del error
partida: totes les dades de la partida
/login nick: pseudònim de l'usuari
email: adreça electrònica
status: ok/error
msg: detalls del error
uid: identificador d'usuari
/mou uid: usuari
pid: id de partida
fila_inici
col_inici
fila_dst
col_dst
status: ok/error
msg: detalls del error
partida: totes les dades de la partida


Ús de la API i comprovacions

Per poder efectuar una partida haurem de seguir el següent procés:

  1. /login : aconsegueixo el meu uid
  2. /en_espera : aconsegueixo llista d'usuaris que volen començar partida
  3. /juga : creem i comencem partida (pid)
  4. /mou : efectuem moviments en la partida

El WS ha de controlar la partida. Per tant haurà de comprovar una sèrie de regles per donar un moviment per bo (en el mètode mou):

  • Comprovar que el lloc de destí és correcte per la peça a l'origen.
  • Comprovar que entremig del origen i destí no hi ha alguna peça obstaculitzant el pas (excepte pel cavall)
  • Comprovar si al lloc de destí hi ha una peça enemiga, i si la hi ha, eliminar-la de la partida.
  • Comprovar si el moviment ha creat una situació d'escac i mat, fet que acabaria la partida.
  • Retornar {status:true} o {status:false} si el moviment és correcte.


Recomanacions

  • Instal·la mongodb, pymongo i cherrypy
  • Crea el servidor bàsic amb cherrypy com en l'exemple del final.
  • Crea el endpoint /login com l'exemple, i afegeix les comprovacions:
    • Si existeix el mateix email i nick, retorna el uid existent
    • Si existeix el mateix email modifica el nick i retorna el uid
    • Si existeix el mateix nick amb diferent email li retorna error
  • Fes un mètode (p.ex. /juga) que crei una partida amb les figures amb la posició inicial


Servei bàsic amb CherryPy

import cherrypy, pymongo
	  
class Escacs(object):
    def __init__(self):
        self.client = pymongo.MongoClient()
        self.db = self.client.escacs
        self.usuaris = self.db.usuaris
        self.partides = self.db.partides
    
    @cherrypy.expose
    def index(self):
        return "SUPER ESCACS !!!!"

    @cherrypy.expose
    @cherrypy.tools.json_in()
    @cherrypy.tools.json_out()
    def login(self):
        # agafem dades
        dades_in = cherrypy.request.json
        email = dades_in["email"]
        nick = dades_in["nick"]
        # guardem l'usuari
        uid = self.usuaris.save( {"email":email,"nick":nick,"estat":"en espera"} )
        usuari = self.usuaris.find_one( {"_id":uid} )
        # transformem el _id en string per que sigui JSON-serializable (si no, dona error)
        usuari["_id"] = str(uid)
        # retornem dades d'usuari
        return usuari

cherrypy.quickstart( Escacs() )


Testejant l'exemple amb UnitTest

Podeu anar a Unit Tests en Python per veure com efectuar tests sobre aquest WS.