diseno

Diseño de Linkero

El diseño de Linkero hace fuerte hincapié en 5 aspectos:

• Propósito general
• Modular
• Escalable
• Segura
• Sencilla

Linkero hace uso de las siguientes librerías:

• Flask
  • flask_restful
  • flask_sqlalchemy
  • flask_httpauth
• It´s Dangerous
• PassLib
• Common (funciones de propósito general)
  • SimplePythonTools

Fichero de Configuración

La configuración de Linkero se carga desde el fichero config.json en el directorio config\config.json.

La inexistencia de ese fichero o la incorrecta parametrización dentro del mismo, provocará el cierre prematuro de Linkero.

Los parámetros contenidos en el fichero son:

• debug: Booleano que indica si Linkero se lanzará en modo Release (false) o Debug (true)
• tokenLife: Tiempo en segundos para la vida del Token
• adminSecret: Hash del password del admin para la creación de usuarios nuevos
• app: Configuraciones específicas de la APP de Linkero
  • secretKey: Frase secreta
  • databaseUri: Uri de la base de datos SQLite
  • commitOnTeardown: Booleano que indica si lo cambios se harán persistente al temrminar la aplicación
• host: Configuración del Hosting del servicio
  • ip: Dirección IP dónde el servicio escuchará
  • port: Puerto específico donde el servicio escuchará

Dentro del directorio config existe un fichero config-schema.json que puede servir a modo de ejemplo.

Crear una API

Linkero incluye un API de ejemplo llamada testAPI.py para que sirva de modelo.

La partes imprescindibles de toda API para Linkero son:

1. Incluir linkero

   import linkero

2. Cargar las estructuras de datos necesarias

   TODOS = {
       'todo1': {'task': 'build an API'},
       'todo2': {'task': '?????'},
       'todo3': {'task': 'profit!'}
   }
   

3. Crear las clases con los métodos que serán invocados en las llamadas.

   class Todo(linkero.Resource):
   
       @linkero.auth.login_required
       def get(self, todo_id):
           if todo_id not in TODOS:
               linkero.abort(404, message="Todo {} doesn't exist".format(todo_id))
           return TODOS[todo_id]
   

   La línea @linkero.auth.login_required obliga a autenticarnos al hacer la petición del recursos. No olvides incluirlo en todos los recursos que quieras securizar.

4. Configurar la ruta de acceso del recurso en la Api

   def loadTestAPI():    
       linkero.api.add_resource(Todo, '/todos/<todo_id>')
   

Si precisamos de un parser de sintaxis para la estructura de datos podemos usar:

    parser = linkero.reqparse.RequestParser()
    parser.add_argument('task')

De esta forma se define el argumento task en el parser y si necesitamos añadir un elemento a la estructura de datos, podremos hacerlo parseando la petición con el parser:

    class Todo(linkero.Resource):

        @linkero.auth.login_required
        def get(self, todo_id):
            if todo_id not in TODOS:
                linkero.abort(404, message="Todo {} doesn't exist".format(todo_id))
            return TODOS[todo_id]

        @linkero.auth.login_required
        def put(self, todo_id):
            args = parser.parse_args()
            task = {'task': args['task']}
            TODOS[todo_id] = task
            return task, 201

No olvides incluir @linkero.auth.login_required si quieres securizar el recurso.

Poner en marcha una API con Linkero

Para poner en marcha una API creada para Linkero basta con crear un main que :

1. Importe a Linkero
2. Importe la API que queramos cargar
3. Invoque el método load que cargue la API loadXXXAPI()
4. Ejecute Linkero

# 1) Linkero Core
import linkero

# 2) APIs developed to use with Linkero
import testAPI

# 3) Load desired APIs
testAPI.loadTestAPI()

# 4) Run Linkero
linkero.run()

Códigos de Estado

La gestión de códigos de respuesta debe estar sujeta a la descrita en la siguiente tabla:

HTTP Verb	CRUD	Entire Collection (e.g. /customers)	Specific Item (e.g. /customers/{id})
POST	Create	201 (Created), ‘Location’ header with link to /customers/{id} containing new ID.	404 (Not Found), 409 (Conflict) if resource already exists..
GET	Read	200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists.	200 (OK), single customer. 404 (Not Found), if ID not found or invalid.
PUT	Update/Replace	404 (Not Found), unless you want to update/replace every resource in the entire collection.	200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH	Update/Modify	404 (Not Found), unless you want to modify the collection itself.	200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
DELETE	Delete	404 (Not Found), unless you want to delete the whole collection—not often desirable.	200 (OK). 404 (Not Found), if ID not found or invalid.

Más información

Para todos los métodos puede devolverse el código 401 que implica un acceso no autorizado.

Las razones más habituales son:

• No se han proporcionado credenciales de autenticación correctas
• El token de acceso no es válido por haber caducado el token