Ecomap API Documentation

Ecomap.org is a web service build on RESTful Api concept. It has web-application, ios and android based clients

API start

This module holds all views controls for ecomap project.

GET /

Controller starts main application page. Shows initial data of application, renders template with built-in Angular JS.

Return:renders html template with angular app.
views.index()[source]

Admin API

Module contains routes, used for admin page.

resources

admin_views.resource_post()[source]

this routes handles REST operations with site resources

@login_required

access for role:
admin
request headers:
 
  • Accept: application/json, text/plain, */*
  • Authorization: remember_token to authenticate
response header:
 
  • Content-Type: application/json
GET /api/resources

Function which returns resources list from db with pagination options.

Rtype:

JSON
Query Parameters:
 
  • offset – offset number. default is 0
  • limit – limit number. default is 5
Return:
  • If resource list is not empty:

    [[{"resource_name": "name", "id": 1}, {"resource_name": "name_2", "id": 2}], [{"total_res_count": 2}]]

  • If there are no resources:

    {}
Status Codes:
POST /api/resources

Function which adds new site resource to site-map in admin panel.

Rtype:

JSON
Request agrs:

{resource_name: “/res_name”}
Return:
  • If there is already resource with this name:

    {'error': 'resource already exists'}

  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'added_resource': 'resource_name', 'resource_id': 'resource_id'}
Status Codes:
  • 400 Bad Request – resource already exists or request is invalid
  • 200 OK – resource was successfully posted
PUT /api/resources

Function which edits resource name by its id.

Rtype:

JSON
Request args:

{resource_name: “new_res_name”, resource_id: 29}
Return:
  • If there is already resource with this name:

    {'error': 'this name already exists'}

  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'status': 'success', 'edited': 'resource_name'}
Status Codes:
  • 400 Bad Request – resource already exists or request is invalid
  • 200 OK – resource was successfully posted
DELETE /api/resources

Function which deletes resource from database by id. Before delete checks if resource have any permissions.

Rtype:

JSON
Request args:

{resource_id: 29}
Return:
  • If resource has assigned permissions:

    {'error': 'Cannot delete!'}

  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'status': 'success', 'deleted_resource': 'resource_id'}
Status Codes:
  • 400 Bad Request – if resource has assigned permissions or request invalid
  • 200 OK – resource was deleted successfully

permissions

admin_views.permission_post()[source]

this group of rotes provides control of permissions to site resources URLs

@login_required

access for role:
admin
request headers:
 
  • Accept: application/json, text/plain, */*
  • Authorization: remember_token to authenticate
response header:
 
  • Content-Type: application/json
GET /api/permissions

Function which gets all permissions.

Rtype:

JSON
Query Parameters:
 
  • resource_id – id of site resource(int)
Return:
  • If resource list is not empty for this id:

    {'permission_id': 'permission_id', 'action': 'action', 'modifier': 'modifier', 'description': 'description'}

  • If there are no permissions for selected resource_id:

    {}
Status Codes:
POST /api/permissions

Function which adds new permission into database.

Rtype:

JSON
Request args example:
 

{action: “DELETE”, description: “TEST”, modifier: “None”, resource_id: “33”}
Return:
  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'added_permission': 'description', 'permission_id': 'permission_id'}
Status Codes:
PUT /api/permissions

Function which edits permission.

Rtype:

JSON
Request args example:
 

{action: “POST”, description: “edited description”, modifier: “Any”, resource_id: “33”}
Return:
  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'status': 'success', 'edited_perm_id': 'permission_id'}
Status Codes:
DELETE /api/permissions

Function which deletes permission by it id.

Rtype:

JSON
Request args example:
 

{permission_id: 5}
Return:
  • If permission was binded to some role:

    {'error': 'Cannot delete!'}

  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'status': 'success', 'edited_perm_id': 'permission_id'}
Status Codes:
GET /api/all_permissions

Function sends all created permissions to frontend. Handles with pagination options defined in query arguments.

Rtype:

JSON
Query Parameters:
 
  • offset – pgination offset number. default is 0
  • limit – pagination limit number. default is 5
Return:
  • If permission tuple from DB is not empty:

    [[{"action": "POST", "permission_id": 6, "resource_name": "/api/register", "modifier": "Any", "description": "register user into app"}], [{"total_perm_count": 46}]]

  • If there are no permissions:

    {}
Status Codes:

roles

admin_views.role_post()[source]

this routes handles REST operations with site role base access control

@login_required

access for role:
admin
request headers:
 
  • Accept: application/json, text/plain, */*
  • Authorization: remember_token to authenticate
response header:
 
  • Content-Type: application/json
GET /api/roles

Function which gets all roles of user from database.

Rtype:

JSON
Return:
  • If no roles in DB:

    {}

  • If roles exists:

    {'role_name': 'role_id',..., 'role_name2': 'role_id'}
Status Codes:
POST /api/roles

Function which adds new role into database.

Rtype:

JSON
Request args:

{“role_name”:”test”}
Return:
  • If there is already role with this name:

    {'error': 'role already exists'}

  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'added_role': 'role_name', 'added_role_id': 'role_id'}
Status Codes:
PUT /api/roles

Function which edits role name by it id.

Rtype:

JSON
Request args:

{role_name: “new_name”, role_id: 5}
Return:
  • If there is already resource with this name:

    {'error': 'this name already exists'}

  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'status': 'success', 'edited': 'resource_name'}
Status Codes:
DELETE /api/roles

Function which deletes role from database by it id.

Rtype:

JSON
Request args:

{role_id: 5}
Return:
  • If role has permissions:

    {'error': 'Cannot delete!'}

  • If request data is invalid:

    {'status': False, error: [list of errors]}

  • If all ok:

    {'status': 'success', 'deleted_role': 'role_id'}
Status Codes:
POST /api/user_roles

Function, used to get all users.

Return:list of all users with id, first name, last name, email and role

[{"role": "admin", "first_name": "Admin", "last_name": "Administrator", "user_id": 3, "email": "admin@ecomap.com"} ... {"role": "user", "first_name": "Oleg", "last_name": "Lyashko", "user_id": 4, "email": "radical@gmail.com"}

Status Codes:
GET /api/user_roles

Function, used to get all users.

Return:list of all users with id, first name, last name, email and role

[{"role": "admin", "first_name": "Admin", "last_name": "Administrator", "user_id": 3, "email": "admin@ecomap.com"} ... {"role": "user", "first_name": "Oleg", "last_name": "Lyashko", "user_id": 4, "email": "radical@gmail.com"}

Status Codes:
GET /api/user_page

Function which returns users list from db with pagination options.

Rtype:

JSON
Query Parameters:
 
  • offset – pagination offset number. default is 0
  • limit – pagination limit number. default is 5
Return:

[[{"role_name": "admin", "first_name": "username", "last_name": "UserSurname", "id": 1, "email": "email@name.ru"}, .... {"role_name": "user", "first_name": "Username", "last_name": "UserSurname", "id": 5, "email": "email@gmail.com"}], [{"total_users": 2}]]
Status Codes:

role_permission

admin_views.role_permission_post()[source]

this routes handles REST operations with site role base access control

@login_required

access for role:
admin
request headers:
 
  • Accept: application/json, text/plain, */*
  • Authorization: remember_token to authenticate
response header:
 
  • Content-Type: application/json
GET /api/role_permissions

Function which gets all permissions from database and all actual permissions for current role.

Query Parameters:
 
  • role_id – set specific id of user role for showing its actual list of permissions
Return:

{'actual': [list of actual permissions for role], 'all_permissions': [list of all permissions]}
Rtype:

JSON
POST /api/role_permissions

Function which binds permission with role.

Rtype:

JSON
Request args example:
 

{permission_id: 5, role_id: 4}
Return:
  • If request data is not valid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'added_role_permission_for_role': 'role_id'}
Status Codes:
PUT /api/role_permissions

Function which sets list of permission to role. Before sets removes all permissions from role.

Rtype:

JSON
Request args example:
 

{permission_id: 5, role_id: 4}
Return:
  • If request data is not invalid’:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'msg': 'edited permission'}
DELETE /api/role_permissions

Function to delete permissions by role id.

Rtype:

JSON
Request args example:
 

{role_id: 4}
Return:
  • If request data is not invalid’:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {'msg': 'deleted permission'}

Static Pages API

POST /api/addResource

This method adds new page to db.

Rtype:

JSON
Request agrs:

{‘title’: ‘new page’, ‘alias’: ‘tag’, ‘description’: ‘short description of page’, ‘content’: ‘main article content’, ‘meta_keywords’: ‘keyword1, keyword2’, ‘meta_description’: ‘meta-description of content’, ‘is_enabled’: 1}
Return:
  • If there is already page with this name:

    {'result': 'False', 'msg': 'Page already exists!'}

  • If request data is invalid:

    {'result': 'False', 'msg': 'Couldn't add new page!'}

  • If all ok:

    {'result': 'True', 'msg': 'Succesfully added!'}
Status Codes:
  • 200 OK – check status in response json object
PUT /api/editResource/(int: page_id)

This method makes changes to given page(ex-resource) via page_id, passed to it.

Parameters:
  • page_id – id of specific page to edit.
Request agrs example:
 

{‘id’: 1, ‘title’: ‘title’, ‘alias’: ‘tag’, ‘description’: ‘small description of page’, ‘content’: ‘main article content’, ‘meta_keywords’: ‘keyword1, keyword2’, ‘meta_description’: ‘meta-description of content’, ‘is_enabled’: 1}
Return:

confirmation object
Rtype:

JSON
JSON sample:

{'result': true} or {'result': false}
Status Codes:
DELETE /api/deleteResource/(page_id)

This method deletes page by it’s id.

Parameters:
  • page_id – id of specific page to delete.
Request agrs example:
 

{‘id’: 1}
Return:

confirmation object
Rtype:

JSON
JSON sample:

{'result': true, 'msg': 'Page was deleted successfully!'}
or
{'result': false, 'msg': 'Couldn't delete the page'}
Status Codes:
GET /api/getTitles

This method returns short info about all defined static pages.

Return:list of dicts with title, id, alias and is_enabled
Rtype:JSON
JSON sample:[{'is_enabled': 1, 'alias': 'alias_Tag', 'id': 1, 'title': 'Custom_Title'}, {'is_enabled': 1, 'alias': 'Tag', 'id': 2, 'title': 'AnotherTitle'}]
GET /api/resources/(alias)

This method retrieves exact faq page(ex-resource) via alias, passed to it.

Parameters:
  • alias – url path to specific static page.
Return:

object with all page’s attributes within a list or 404 status.
Rtype:

JSON
JSON sample:

[{'id': 1, 'title': 'title', 'alias': 'tag', 'description': 'small description of page', 'content': 'main article content', 'meta_keywords': 'keyword1, keyword2', 'meta_description': 'meta-description of content', 'is_enabled': 1}]

User API

main application api

authentication

routes provides site logging and app authentication functions

Module contains routes for user authorization, registering and logout.

authorize_views.register()[source]
POST /api/register

Method for registration new user in db. Method checks if user is not exists and handle registration processes.

Rtype:

JSON
Request args:

{‘first_name’: ‘Ivan’, ‘last_name’: ‘Sirko’, ‘email’: ‘email@test.com’, ‘password’: ‘passw’}
Return:
  • if one of the field is incorrect or empty:

    {'error':'Unauthorized'}

  • if user already exists

    {'status': 'user with this email already exists'}

  • if registration was successful:

    {'status': added user <username>}
Status Codes:
POST /api/login

Login processes handler. Log user in or shows error messages.

Rtype:

JSON
Request args:

{‘email’: ‘username@mail.com’, ‘password’: ‘userpaswd’}
Return:
  • if credentials are ok and log in successful:

    {"email": "username@mail.com", "iat": "???", "id": 6, "name": "oleg", "role": "admin", "surname": "lyashko", "token": "hashed_auth_token"}

  • if user with entered email isn’t exists or password was invalid:

    {'error':'message'}
Status Codes:
POST /api/logout

Method for user’s log out.

Rtype:

JSON
Return:
  • if logging out was successful:

    {result:True}

  • in case of problems:

    {result:False}
GET /api/logout

Method for user’s log out.

Rtype:

JSON
Return:
  • if logging out was successful:

    {result:True}

  • in case of problems:

    {result:False}
POST /api/email_exist

Function for AJAX call from frontend. Validates unique email identifier before registering a new user :return: json with status 200 or 400

POST /api/authorize/(provider)

Provides facebook authorization. Retrieves user info from facebook, check if there is user with retrieved from facebook user id, :param provider: Oauth provider (Facebook by default)

  • if yes:

    skips to next step

  • if not:

    checks if there is user with retrieved email - if yes:

    adds oauth credentials to this user

    • if not:

      creates new user

After all function logging in user into app and return it’s params

GET /api/authorize/(provider)

Provides facebook authorization. Retrieves user info from facebook, check if there is user with retrieved from facebook user id, :param provider: Oauth provider (Facebook by default)

  • if yes:

    skips to next step

  • if not:

    checks if there is user with retrieved email - if yes:

    adds oauth credentials to this user

    • if not:

      creates new user

After all function logging in user into app and return it’s params

restore user password

routes provides restoring user account password

POST /api/restore_password

Function to restore forgotten password.

Rtype:

JSON
Request args:

{‘email’: ‘username@mail.com’}
Return:
  • if credentials are ok and checking successful:

    {message='Email was sended.'}

  • if user’s email isn’t exists:

    {'error':'There is not such email.'}
Status Codes:
GET /api/restore_password_page/(string: hashed)

Renders page template to restore password. :param hashed: unique hash to identify user via sending it to email.

:return redirect to main page with rendered template.

PUT /api/restore_password

Updates user password.

change user password

POST /api/change_password

Function, used to change user password.

Rtype:

JSON
Request agrs:

{id: “6”, old_pass: “oldpasswd”, password: “newpasswd”}
Return:
statuscode 400:request is invalid or old password not confirmed
statuscode 200:password was successfully changed

user profile

GET /api/user_detailed_info/(int: user_id)

This method returns json object with user data.

Parameters:
  • user_id – id of user for viewing detailed info
Rtype:

JSON
Return:
  • If user exists and data provided:

    {"avatar": "/uploads/user_profile/userid_6/profile_id6.png", "email": "email@email.com", "name": "Firstname", "role": "admin", "surname": "Lastname"}

  • If there is no user with given email:

    {status:'There is no user with given email'}
Status Codes:
POST /api/user_avatar

Controller provides add and edit function for user’s profile photo.

Content-type:

multipart/form-data
Form Parameters:
 
  • name – name of image file (‘photo.jpg’)
  • file – image file in base64. Content-Type: image/png
Rtype:

JSON
Return:

json object with image path if success or 400 error message

  • If request data is invalid:

    {'error': 'error with import file'}

  • If all ok:

    {added_file: "/uploads/user_profile/userid_6/profile_id6.png"}
Status Codes:
DELETE /api/user_avatar

Controller for handling deleting user’s profile photo.

Request args:

{‘user_id’: ‘6’}
Rtype:

JSON
Return:

json object with success message or message with error status

  • If all ok:

    {deleted_avatar: "6", msg: "success"}
Status Codes:

Problem API

routes handling API connected with adding and managing environment problems

adding and viewing problems

Module contains routes, used for problem table.

problem_views.problems()[source]
GET /api/problems

Handler for sending short data about all problem stored in db. Used by Google Map instance.

Rtype:

JSON
Return:
  • If problems list not empty:

    [{"status": "Unsolved", "problem_type_Id": 2, "title": "problem 1","longitude": 25.9717, "date": 1450735578, "latitude": 50.2893, "problem_id": 75}, {"status": "Unsolved", "problem_type_Id": 3, "title": "problem 2", "longitude": 24.7852, "date": 1450738061, "latitude": 49.205, "problem_id": 76}]

  • If problem list is empty:

    {}
Status Codes:
GET /api/problem_detailed_info/(int: problem_id)

This method returns object with detailed problem data.

Rtype:

JSON
Parameters:
  • problem_id – {problem_id: 82}
Return:
  • If problem exists:

    [[{"content": "Text with situation", "status": "Unsolved", "date": 1450954447, "severity": "1", "title": "problem", "latitude": 52.7762, "proposal": "proposal how to solve", "problem_type_id": 3, "problem_id": 82, "longitude": 34.2114}], [{"activity_type": "Added", "user_id": 5, "problem_id": 82, "created_date": 1450954447}], [{"url": "/uploads/problems/82/0d0d3ef56a16bd069e.png", "user_id": 5, "description": "description to photo"}], [{"user_id": 5, "name": "User", "problem_id": 82, "content": "Comment", "created_date": 1450954929000, "id": 5}]]

  • If problem not exists:

    {"message": " resource not exists"}
Status Codes:
POST /api/problem_post

Function which adds data about created problem into DB.

Content-type:

multipart/form-data
Form Parameters:
 
  • title – Title of problem (‘problem with rivers’)
  • type – id of problem type (2)
  • lat – lat coordinates (49.8256101)
  • longitude – lon coordinates (24.0600542)
  • content – description of problem (‘some text’)
  • proposal – proposition for solving problem (‘text’)
Rtype:

JSON
Return:
  • If request data is invalid:

    {'status': False, 'error': [list of errors]}

  • If all ok:

    {"added_problem": "problem title", "problem_id": 83}
Status Codes:
GET /api/usersProblem/(int: user_id)

This method retrieves all user’s problem from db and shows it in user profile page on my problems tab.

rtype:

JSON
param user_id:

id of user (int)
return:
  • If user has problems:

    [{"id": 190,"title": "name", "latitude": 51.419765, "longitude": 29.520264, "problem_type_id": 1, "status": 0, "date": "2015-02-24T14:27:22.000Z", "severity": '3', "is_enabled": 1 },{...}]

  • If user haven’t:

    {}
statuscode 200:

no errors
GET /api/all_usersProblem

This method retrieves all user’s problem from db.

Query Parameters:
 
  • limit – limit number. default is 5
  • offset – offset number. default is 0
Rtype:

JSON
Return:

list of user’s problem represented with next objects:

[{"id": 190, "title": "name", "latitude": 51.419765, "longitude": 29.520264, "problem_type_id": 1, "status": 0, "date": "2015-02-24T14:27:22.000Z", "severity": '3', "is_enabled": 1},...]

photos

POST /api/photo/(int: problem_id)

Controller for handling adding problem photos.

param problem_id - id of problem instance for uploading new photos.

Content-type:

multipart/form-data
Form Parameters:
 
  • file – image file in base64. Content-Type: image/png
  • name – image name (‘image.jpg’)
  • description – description of image (‘some text’)
Return:

json object with success message or message with error status.

  • if success:

    {"added_file": "/uploads/problems/77/df4c22114eb24442e8b6.png"}
Status Codes:

comments

functions for adding and viewing comments of problems

POST /api/problem/add_comment

Adds new comment to problem.

Rtype:

JSON
Request args:

{content: “comment”, problem_id: “77”}
Return:
  • if success:

    {"message": "Comment successfully added."}

  • if some error:

    {error: "type of validation error"}
Status Codes:
GET /api/problem_comments/(int: problem_id)

Return all problem comments

Rtype:

JSON
Parameters:
  • problem_id – id of problem (int)
Return:
  • If problem has comments:

    [{content: "some comment", created_date: 1451001050000, id: 29, name: "user name", problem_id: 77, user_id: 6, },{...}]

  • If user hasn’t:

    {}
Status Codes: