HOST: http://aidmaid.net/api
Before jumping into API endpoints, let me describe the architecture of the whole system. The server are based on Amazon EC2 instances which are running behind the Elastic Load Balancer. Database is hosted on Amazon RDS (MySql) and Apache/Slim is used to construct Restful APIs. The apps (iOS and Android) is using Amazon Cognito, that provide identity to all the app users. Currently we are not using authenticated identites, all identites are treated as guests.
All API endpoints with few exceptions (like register, login) should be called with authenticated headers. The header must have SHA1 value of user's uid (Universal Identified provided from Cognito). That SHA1(uid) would be checked before entertaining any request. If server did not find any uid
present in the database, it will return 400 response code. That would indicate your request is not valid.
We are using Amazon SNS for push notification for both platforms. When an app run, the Amazon gives the app and uid (Cognito) and Push Arn (SNS). We would be using these two values in various API calls.
There are two types of registration in AidMaid, one is from the Facebook and one is in-app registration. Facebook registration is not implemented as it suppose to be. But we kind a get our system working with it.
In case of Facebook login button, user authenticate from facebook, on return we grab basic info permissions for user account. Then we just get name
and email
from their API. We use this information to populate our own registration page. Remember in case of Facebook login, user would not enter the password
in registration page. So his email, name and password would be automatically populated and disabled for editing. On registration page, he just have to supply phone number.
In case of AidMaid regsitration, user will have to provide all of the required information on the screen along with his photo. Cognito uid
should be sent in the headers as uid
field
Then you can call the register_email endpoint.
For Normal user, everything is straightforward, last isaidmaid
should be 1 in case of in-app registration.
For Facebook user, isaidmaid
should be 0, password should be sha1(email)
In final call you should send sha1 of password
Example: In simple case user entered password as 'abcdef' You would send in API call sha1(abcdef) In Facebook case, lets say emai is '[email protected]' The password you would send in the api call would be sha1(sha1([email protected]))
Save all the information in your local storage as well, other than password, you will be using this information in other screens of the app.
- Parameters
- name (string)
- phone (string)
- pusharn (string)
- email (string)
- password (string)
- isaidmaid
-
Response 200 (application/json)
{ "Status": "true", "points": "100" }
After registering the user on the server, you should upload his/her profile picture using this endpoint. It uses multipart request to upload the image. This would be first authenticated request you would be making. Add sha1(uid) in the request header for uid
field. And image
in the form data and post the request. This would be stored on the server, don't worry about he response at this moment. If you have constructed the right request, you can see the actualy image on http://aidmaid.io/api/picture/sha1(uid)
You can see my picture at ``
In Login, make the POST request to the endpoint, put uid
in the request header and call the API endpoint with email
and password
fields.
Make sure you send the sha1 value of the password in the API call, plain password won't authenticate the user from the server. In response please store all the values in your local storage for further call. Here store the returned uid
from the response and use this uid
in later requests for authentication. Not the one which is provided by Cognito. That will be only used once for registering the user. Now at this points you might have different cognito identity and server returned identity. But you carry on server returned uid
-
Parameters
- email (string)
- password (string)
-
Response 200 (application/json)
{ "status": "true", "user": { "name": "Sarmad Makhdoom", "phone": "+92334444444", "uid": "us-east-1:123xxx....", "points": "points" } }
In order to reset the user password, take its valid email address from the app and sent it to the /reset_password
endpoint. Don't worry about the response here if you have valid request. Server will automatically call the reset password routine, send email, allow user to change the password from the link sent in the email. You don't have to worry about that at this moment.
- Parameters
- email (string)
To update a user profile, username
is the key for this call, the server will automatically
update the user profile on performing POST call. ON successfuly call, it will return a JSON
result which have Status
value to be OK, otherwise it will be FAIL.
`password' is an option paramter here, if provided then the server will change this user password and if it is not provided, it will just update the rest of the values for the user profile.
- Parameters
- username (string)
- password (optional,string)
- fullname (string)
- phone (string)
- email (string)
-
Response 200 (application/json)
{ "Status": "OK", "Data": { "userid": "7", "username": "sarmad11", "fullname": "sarmad makhdoom", "phone": "+923344", "email": "[email protected]" } }
To authenticate user for the system, this endpoint will entertain your request for login query.
There is only two required paramaters which are username
and password
. Username can be
actual username of the user or the email address he/she used while signup. It will return the same
JSON structure which was return after signup, Status
will return either OK or FAIL
and Data
field will have all the user information, like userid, fullname etc.
And yeah, previously we don't have user based system in AidMaid and users can post anonymously
in the system, so all the users who are currently not logged in and/or from the previous AidMaid version,
we have userid
assigned 1 for them. So if user is not logged in and try to post an alert
in the system, those alerts SHOULD be posted with userid 1 not with NULL.
-
Parameters
- username (string)
- password (string)
-
Response 200 (application/json)
{ "Status": "OK", "Data": { "userid": "7", "username": "sarmad11", "fullname": "sarmad makhdoom", "phone": "+923344", "email": "[email protected]" } }
To display global alerts on the Network page, this endpoint is used. It will return all global alerts which are
posted in last 24 hours, the format of the result can be seen in the response section, mostly
it will return the userid
who posted the alert, fullename
, message
, etc for the panic alert.
Use them in the application you want and format datetime accordingly.
Moreover, this takes two optional parameters for paging, like if you want to present total alerts in different pages
so you can instead of taking all the global alerts, just provide page
and pageSize
GET parameters
page
starts from 0 and then you can set the pageSize
like for 25, so you will get first page of 25 alerts,
similarly you can move further with page
1 and same pageSize variable.
- Parameters
- page (optional, integer)
- pageSize (optional, integer)
-
Response 200 (application/json)
[ { "userid":"1", "fullname":"Anonymous", "country":"Saudi Arabia", "message":"I NEED HELP IMMEDIATELY PELASE", "lat":"21.645660000000000", "long":"39.122750000000000", "datetime":"09:36 03.12.2015" }, .... ]
Similarly like global alerts, we can take local alerts from the /posts_local
endpoint,
here we need to provide three required paramters in POST request, lat
, lon
, rad
. Where
lat and lon are straight-forward which represent user's latitude and longitude. rad
is Radius here,
in local alerts we need to send a radius value and server will return all alerts from that radius starting from provided
lat and lon values.
Moreover, paging works like global alert here as well, these are optional paramters here as well, but I suggest one should use them in order to avoid a long list download from the server on the app.
- Parameters
- lat (float) - Latitude of the center poitn
- lon (float) - Longitude of the center point
- rad (float) - Radius of the area
- page (optional, integer)
- pageSize (optional, integer)
-
Response 200 (application/json)
[ { "userid":"1", "fullname":"Anonymous", "country":"Saudi Arabia", "message":"I NEED HELP IMMEDIATELY PELASE", "lat":"21.645660000000000", "long":"39.122750000000000", "datetime":"09:36 03.12.2015" }, .... ]
In order to post an alert in AidMaid system, we have to use /add_alert
endpoint, and all the parameters are
required here, which are self-explainatory, on return a boolean value is return to confirm that
new alert has been posted or not.
-
Parameters
- userid (int)
- lat (float)
- lon (float)
- country (string)
- message (string)
-
Response 200 (application/json)
{ "status":"OK", "isPosted":false }
You have to POST to this url with image file and the user id, it works just like a simple HTML multipart/form-data type request, make sure to resize the image before uploading, Any prefered size that you think should be used in your app can be uploaded, there is no limit on the server side.
-
Parameters
- userid (int)
- imgfile (binary data)
-
Response 200 (text/html)
{ }
To download uploaded user profile picture, you have to pass the user id to the GET url in this request and user profile picture is returned. If user id is not present on the server or the image is not yet uploaded, it will return default AidMaid anonymous image placeholder image in red color.
-
Response 200 (image/jpeg)
{ }
Let me explain how live video streaming works in v2.3 of the AidMaid, we take off the image/audio uploading in that version and moved only to live video streaming. So currently no API is available to do that, just functions are present to make possible the video streaming.
How this system works, first of all when a user start streaming on AidMaid, the app connects with the server
and take a token
which is a random string of length 10. It can be letters or numbers, this token also
initialize the server for the streaming. I recommend saving that token
in the user preference on the mobile
so that it can reused when a user stream. But if somehow it is lost, you can generate a new token
from the server. Because we are currently not removing data from the server of a particular token
that is why I am suggesting to keeping it at a safe palce. You will need this token for Red5Pro server as well,
because this is the token you will be sending to the receiver side as an SMS. And all the information
can be retrieved from the server from this token easily.
After getting the token from the server. The first thing to do is to sync user position from the
app to the server, there is an endpoint for that, where you will post userid
, latitude
and longitude
on the server. You will keep sending this information after (either a regular interval or user changes its positions).
Select any method you feel comfortable with, I personally choosed position changed event in iOS app to sync with the server.
There is another endpoint from which you will get position, name of the user and time of last update on the server by supplying token.
So here is the workflow of the live video stream.
- User start streaming
- New Token is generated from the server
- Sender sync its position with user id with the server
- Sender start live streaming with Red5Server and the stream name would be token
- Sender send a SMS to the Receiver (a link with the token, explain later)
- Receiver open that link and it will open the app
- Receiver retrieve the information from the server with that token
- Receiver show the information and start receving the live steream from Red5Server
SMS Sending: You can send SMS to the user with the link http://aidmaid.net/live/{token}
if the app is installed, it will open it using scheme aidmaid://token
or open the webpage where
it shows the live position of the user and option for tracking.
Get and init random token from the server
-
Response 200 (application/json)
{ "Status":"Done", "Token":"vCkWctZEvJ" }
Upload information on the server
-
Parameters
- token (string)
- userid (int)
- lat (float)
- lon (float)
-
Response 200 (application/json)
{ "Status":"Done" }
Get stream information like user id, name, position, last update time from the server. Here time is UNIX timestamp, you can convert it to any format you like.
-
Parameters
- token (string)
-
Response 200 (application/json)
{ "Status":"OK", "Time":123423434, "userid":2, "lat":37.234234, "lon":-71.234234, "name":"Sarmad Makhdoom", }