design

Linkero design

Linkero design focus on be:

• General purpose
• Modularity
• Escalability
• Security
• Simplicity

Linkero use these libraries:

• Flask
  • flask_restful
  • flask_sqlalchemy
  • flask_httpauth
• It´s Dangerous
• PassLib
• Common (General purpose functions)
  • SimplePythonTools

Config file

Linkero loads its configuration from gile config.json into path config\config.json.

If this file doesnt exist of it has a bad syntax, Linkero will crash immediately.

The parameters needed by config file are:

• debug: Boolean to set Release build (false) o Debug build (true)
• tokenLife: Token´s timelife
• adminSecret: Hash from admin password to create new users
• app: App configuration
  • secretKey: Secret key
  • databaseUri: Uri with SQLite database path.
  • commitOnTeardown: Boolean to set persistent data storate (true) or not.
• host: Configuration
  • ip: Specific IP address where service is listening
  • port: Specific port where service is listening

Inside config folder exist a file called config-schema.json with a config file example.

Create a new API

Linkero has an example api called testAPI.py. Check this file to see how Linkero works. Description of all steps needed:

1. Include linkero library:

   import linkero

2. Load all file inputs

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

3. Create a class with methodos implemented in the new API.

   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]
   

   The line @linkero.auth.login_required force users to be authenticated to send requests and get a response. DON´T forget to include it in all methods.

4. Configure paths to access to API´s resources

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

If you need a syntax parser to read the data you can use:

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

Defining argument task into parser object, if you need any element from the data, you can get it as follow:

    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

DON´T forget to include it in all methods.

Summary to use the new API with Linkero

In summary, a use an API created with Linkero, create a script with main and:

1. Include linkero library
2. Import API to be loaded
3. Call to load loadXXXAPI() method
4. Execute Linkero

In example:

# 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()

State codes

To manage states, follow the next table:

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.

More info

If you get 401 error, you are not properly authenticated.

Probably:

• Your credential are incorrect
• El access token has expired