Skip to content

Latest commit

 

History

History
559 lines (383 loc) · 20.7 KB

README.md

File metadata and controls

559 lines (383 loc) · 20.7 KB

API docs

Clients need a valid API_Key to access the API, and also valid JsonWebTokens for validating api calls after login.

So each HTTP request is expected to have following HEADERS:

 "X-API-Key" :  *API_KEY* (mandatory)
 "x-access-token" : JWT_Token (only required when logged in)
 "Content-Type" : "application/json"
  • NOTE : JWT is required for authorization of requests only after login

For SocketIO (if used) communication, the following extraHeaders are required:

 "x-access-token" : JWT_Token (mandatory)

Base API url : https://secrep.herokuapp.com/

Example endpoints to send requests:

Citizen app => https://secrep.herokuapp.com/signup
Patrol app => https://secrep.herokuapp.com/patrol/login
Admin app => https://secrep.herokuapp.com/admin/login

CONTENTS

Citizens app api

Prefix - NONE

  • Authentication and account settings

    POST /signup (Authenticate patrol and create JWT)
    Request Parameters
    name required data type description
    user YES string Unique username
    password YES string N/A
    wallet_addr optional string Crypto wallet address
    Responses
    http code response
    201 {"user_exists":false, message:"User registered}
    400 {"error": "Username and Password REQUIRED"}
    409 {"message": "Username already taken","user_exists": true}
    POST /login (Authenticates a user, returns JWT)
    Request Parameters
    name required data type description
    user YES string Unique username
    password YES string N/A
    Responses
    http code response
    200 {"login": true, "user_exists": true, "token": str(JWT_token) }
    400 {"error": "Username and Password REQUIRED"}
    401 {"login": false,"user_exists": false}
    401 {"message" : "Incorrect Password", "login": false,"user_exists": true}
    POST /change-wallet (Modifies wallet address)
    • Requires JWT in request HEADERS for authorization
    Request Parameters
    name required data type description
    new_addr YES string New wallet address
    Responses
    http code response
    200 {"message": "Updated wallet address!" }
    GET /init (Validate session)
    • Requires JWT in request HEADERS for authorization

    No request parameters required, except JWT in Header of request to verify session

    Responses
    http code response
    200 {"message": "Valid session" }

  • Creating and handling reports

    *** Requires JWT in request HEADERS for authorization

    GET /get-reports (Returns IDs of reports lodged by the user)
    Parameters

    None

    Responses
    http code response
    200 {"cases": []} - List of case IDs
    POST /new-report (Creates/Lodges a report)
    Request Parameters
    name required data type description
    desc YES string Detailed description of the case
    location YES string Location in text or latitude-longitude
    time YES Datetime object Approximate time
    type YES string Crime category; Type of crime
    offenders - string
    victims - string
    Responses
    http code response
    201 {"uploaded":"success", "user_cases":LIST_of_CaseIds}
    404 {"error":"Cannot find the location specified!!"}
    POST /emergency (Creates/Lodges an emergency situation)EXPERIMENTAL

    This will create a case consuming location of report and finding the nearest 4 authorities

    Request Parameters
    name required data type description
    location YES string Location in text or latitude-longitude
    Responses
    http code response
    201 {"nearest_authority":NearestAuthorityID, "nearest_authorities":LIST_of_NearestAuthorityIds}
    404 {"error":"Cannot find the location specified!!"}
    POST /get-case-info (Returns details of a particular case)
    Request Parameters
    name required data type description
    case_id YES string Obtained from /get-reports
    Responses
    http code response
    200 CASE-OBJECT
    CASE OBJECT SCHEMA
    {
    "_id": case_id,
    "desc": desc,
    "victims": victims,
    "ofenders": ofenders,
    "location": None,
    "time": time,
    "crime_files": files,
    "crime_score": None,
    "classified_ByUser": classified_ByUser,
    "classified_model": None,
    "faces_bymodel": [],
    "Status": "Assigned",
    "authority_assigned": authority_assigned[0]["_id"]
}

Patrol app api

Prefix - /patrol

  • Authentication and account settings

    POST /login (Authenticates patrol)
    Request Parameters
    name required data type description
    PatrolID YES string Unique id of authority/Patrol
    password YES string N/A
    location YES string Current location of Patrol
    Responses
    http code response
    200 {"login": true, "token": JWT, "user_exists": true}
    400 {"error": "No Data Payload!!"}
    401 {"login": false, "user_exists": false}
    401 {"login": false, "user_exists": true}
    POST /update-location (Update patrol location)
    Request Parameters
    name required data type description
    location YES string Current location of Patrol
    Responses
    http code response
    200 {"msg": "update success"
    400 {"error": "No Data Payload!!"}

  • Managing reports

    *** Requires JWT in request HEADERS for authorization

    GET /get-cases (Retrieve assigned cases)
    Responses
    http code response
    200 {"cases": LIST_of_CaseIds }
    404 {"message": "unable to find user"}
    POST /get-case-info (Returns details of a particular case)
    Request Parameters
    name required data type description
    case_id YES string Obtained from /get-reports
    Responses
    http code response
    200 CASE-OBJECT
    CASE OBJECT SCHEMA
    {
    "_id": case_id,
    "desc": desc,
    "victims": victims,
    "ofenders": ofenders,
    "location": None,
    "time": time,
    "crime_files": files,
    "crime_score": None,
    "classified_ByUser": classified_ByUser,
    "classified_model": None,
    "faces_bymodel": [],
    "Status": "Assigned",
    "authority_assigned": authority_assigned[0]["_id"]
}
    POST /case-status (Update status of a case)
    Request Parameters
    name required data type description
    case_id YES string ID of case to be updated
    status YES string new status for the case

    Accepted status(es) :

    • insufficient
    • Assigned
    • Resolved
    • Duplicate
    • Unassigned
    Responses
    http code response
    200 insufficient - {"msg":"Status Updated"}
    200 Assigned - {"msg":"Status Updated"}
    200 Resolved - {"transaction_hash": TXN_HASH }
    200 Resolved - {"error": "unable to send cryptocurrency" }
    204 Duplicate - {"msg":"Case removed"}
    200 Unassigned - {"msg":"Status updated"}
    404 {"error": "Trying to update status of unassigned case"}
    400 {"error": "No Data Payload!!"}

Admin api

Prefix - /admin

  • Authentication and retrieval of data

    POST /login (Authenticate admin)
    Request Parameters
    name required data type description
    user YES string Unique admin id
    password YES string N/A
    Responses
    http code response
    200 {"login": true, "token": JWT, "user_exists": true}
    400 {"error": "No Data payload!!"}
    401 {"login": false, "user_exists": false}
    401 {"login": false, "user_exists": true}
    GET /get-cases (Retrieve cases)

    *** JWT required in request HEADERS

    Responses
    http code response
    200 {"cases" : LIST_of_all_Cases}
    404 {"error": ERROR_MSG }

    Sample case item:

    {
    "_id": case_id,
    "desc": desc,
    "victims": victims,
    "ofenders": ofenders,
    "location": None,
    "time": time,
    "crime_files": files,
    "crime_score": None,
    "classified_ByUser": classified_ByUser,
    "classified_model": None,
    "faces_bymodel": [],
    "Status": "Assigned",
    "wallet_addr": current_user["wallet_addr"],
    "authority_assigned": authority_assigned[0]["_id"]
}

  • Manage Patrol

    *** Requires JWT in request HEADERS for authorization

    POST /add-patrol (Register patrol/authority/PoliceStation)
    Request Parameters
    name required data type description
    PatrolID YES string Unique patrol id
    password YES string N/A
    location YES string In form of text or co-ordinates
    Responses
    http code response
    201 {"user_exists": false} => Successfully created
    409 {"user_exists": true} => Already exists, Conflict
    404 {"error":"Cannot find the location specified!!"}
    400 {"error": "No Data payload!!"}
    DELETE /del-patrol (Remove patrol/authority/PoliceStation)
    Request Parameters
    name required data type description
    PatrolID YES string Unique patrol id
    Responses
    http code response
    200 {"accountDel": true} => Successfully created
    404 {"error":"PatrolID not found"}
    400 {"error": ERROR_MSG}

Working with WebSockets using Socket.IO

  • Server-side has implementation of Socket.IO server API which is based and built on top of WebSocket Protocol
  • To establish and communicate properly via sockets from the client-side,
    it is recommended to use Socket.IO client helper libraries/API
    Example: Socket.IO client API for JavaScript, Socket.IO client for Dart etc.
    For more info and docs on Socket.IO, click here
  • To open a WebSocket connection with server from client, use the following urls to connect
    • Admin - https://secrep.herokuapp.com/admin ; namespace - /admin
    • Patrol - https://secrep.herokuapp.com/patrol ; namespace - /patrol

    NOTE : The above urls are entirely different from traditional http urls and can't be accessed directly like http urls, instead they are called Socket.IO namespaces

  • Checkout basic examples

Events

Implement required events on the client-side documented below...

  • Admin events

    Emitting events to server
    • Get_cases - Fetch cases from DB
    • Get_patrols - Fetch patrol(s) and their assigned cases from DB

    The above 2 events return static latest data from DB like http GET...
    Why not use GET?
    If client already opened a socket connection, why not use socket communication

    Listening to events from server
    • PatrolUpdate - Receive real-time assignments/unassignments of cases to patrol
    • CaseUpdate - Receive real-time updates whenever cases are added/removed/updated, doesn't matter if case is assigned or not, any CUD operation triggered will emit this event from server
    • static-cases - In response to Get_cases, this event returns all case objects
    • static-patrol - In response to Get_patrols, this event returns all patrol documents

  • Patrol events

    Emitting events to server
    • Get_cases - Fetch assigned cases from DB
    Listening to events from server
    • CaseUpdate - Receive real-time updates whenever cases are assigned/unassigned
    • static-cases - In response to Get_cases, this event returns all assigned case_ids