ZhoZho

ZhoZho.md

---

---

ZhoZho project API Documention

APIs are using HTTP/1.2 protocol and best practice of rest Apis in 2015
we have to devlare api responses schema before listing them. all the apis are in HTTP1/1 requests are in variouse verbs such as GET, POST, PUT, DELETE and…, input parameters are from-data to handle the file uploading too. responses are in json/text schema

HTTP response codes

HTTP response codes are all in standard of HTTP1/1

Response Codes

Response codes are included in some categories shown in table blew:

code	description
100	success code in any api result
101	missing a parameter in api inputs
2XX	error codes that can happen in auth apis
3XX	error codes that can happen in contact apis
4XX	error codes that can happen in channel apis
5XX	error codes that can happen in profile apis

Code 100

this response happens when everything is ok and we get the success message from service, so the response message would be:

HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 100,
"message": [some success message]
}

Code 101

some parameters are required in api inputs, also they may have a certain format, type(integer, string, float and …) and range(ex: [1,6] in integers). all the errors about the validation of parameters are included in this error code. response text would be in format below:

HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 101,
"errors": [
{
"code": [error code]
"name": [parameter name 1],
"message": [error message 1],
"slug": [error slug]
}
...
]
}

according to the 101 error. error objects contains some fields. field code is the reason of error. for example required or string (means have to be string). name is the name of field that has error. message is a human readable message for human. slug is the concat of code and name to make a unique error string for each validation error, for example name.code you can get all the validation error slugs here

Code 2XX, 3XX, 4XX, 5XX

this response codes are for various parts of apis. but all of them have a certain schema for response test. that’s written blew:

HTTP/1.1 200 OK
Content-Type: application/json
{
code: XXX
message: [error message]
}

note: error messages are useful in human reading cases, all the messages all wll-formed gramatically in english language and programmer can show them driectly as an error message in project.

API lists

all apis are seperated in two categories:
Crud APIs are that kind of APIs contain all four main actions (Create, Retrive, Update and Delete) every CRUD API has a single end-point to minimal the end-points in APIs list. for example there is a curd API for auto reply messages named autoReply. there are for endpoints based on endpoint autoReply:

End Point	Verb	Action
/autoReply	GET	retrive
/autoReply	PUT	create
/autoReply/[id]	UPDATE	update
/autoReply/[id]	DELETE	delete

Retrive

retrive action get a list of records in response, the verb is GET and there are some default parameters then. first parameter are offset and then limit for records pagination. last parameter in query for searching in records.

Create

create action get’s the required fields in parameter and stores the record in database. all queries are the fields for that document.

Update

update action get’s all the fields they have to be changed and then get the record from end point url. if any parameter where missed or not validated, 101 error’ll return.
update end-point is /autoReply/[id] like autoReply/2 that updates the record by id = 2

Delete

delete action get’s the record id in url parameter and removes it. if record not found 404 would be returned by HTTP Response Code 404:

HTTP/1.1 404 Not Found
Content-Type: application/json
{
code: 404,
message: "record not found"
}

if record found, would be removed from database and a response in HTTP Response Code 200:

HTTP/1.1 200 OK
Content-Type: application/json
{
code: 200,
message: "record removed successfully",
record: { record object }
}

Action APIs are the other kind of APIs that they use to intract with some abillities from service. they’re not crud. they are free to have any verb and any response type. parameters are defined particulary for each one.

Category	End Point	Verb	Title
auth	sendCode	POST	sends code to telegram account
auth	checkCode	POST	check the code sent to telegram
auth	login	POST	login the user in application
auth	logout	POST	logout the user from applocation
auth	removeSession	POST	remove the user’s session
contacts	getContacts	GET	get user’s contacts
contacts	getNoisyContacts	GET	get user’s noisy channels
contacts	getBestContacts	GET	get user’s best contacts
contacts	analyzeContacts	GET	analyze a contact and return response
contacts	getThreadChart	GET	get a volume chart for a thread
contacts	autoReply	CRUD	manage all auto replies
contacts	messageQueue	CRUD	manage all message queues
contacts	autoDestruct	CRUD	manage all auto destructs
channels	getChannels	GET	get all channels that user’s joined
channels	rate	PUT	rate a channel
channels	autoSeen	CRUD	manage all auto seen periods
profile	setMaxGoal	PUT	set max online time goal
profile	getMaxGoal	GET	get max online time goal
profile	getOnlineTimeToday	GET	get time spent online last 24 hours
profile	getOnlineTimeLastWeek	GET	get time spent online last 7 days

/auth

/sendCode POST

sends the code to user’s telegram account and user have to enter it in app.

parameters

title	required
phone	true

/checkCode POST

checks the code that user got in telegram account

parametes

title	required
phone	true
code	true

in case of success for this API returns the a random 16byte string named session_id

/login POST

login the user into application by a new refreshed token

parameters

title	required
phone	true
session_id	true

on success response contains token field and expire.

/logout POST

logout the user and terminate the user’s session on application

parameters

title	required
token	true

/terminateSession POST

terminates the telegram session for application. after calling this method successfully, user have to login again via telegram to use the application services

parameters

title	required
token	true

/contacts

/get GET

get’s all contacts of user from telegram account

parameters

title	required
token	true
offset	false
limit	false
query	false

in case of success call for get response contains a field names results and items are contact would be a json text like:

HTTP/1.1 200 OK
Content-Type: application/json
{
"hits": [count of results based on query, offset and limit],
"matches": [count of results just based on query],
"results": [
{contact response object}
]
}

/getNoisy GET

get’s the contact with most sent messages to user’s account. user usually don’t answers the messages of there is less messages sen’t to that contact from user

parameters

title	required
token	true
offset	false
limit	false

in case of success call for get response contains a field names results and items are contact would be a json text like:

HTTP/1.1 200 OK
Content-Type: application/json
{
"hits": [count of results based on query, offset and limit],
"matches": [count of results just based on query],
"results": [
{contact response object}
]
}

/getBest GET

get’s best contacts form telegram account. best contact are those contacts that user spends more time with them. they have more conversation and more resourses in threads.

parameters

title	required
token	true
offset	false
limit	false

in case of success call for get response contains a field names results and items are contact would be a json text like:

HTTP/1.1 200 OK
Content-Type: application/json
{
"hits": [count of results based on query, offset and limit],
"matches": [count of results just based on query],
"results": [
{contact response object}
]
}

/analyze get

get’s all the important and chart informations about a contact. these informations are how much resources sent and recieved, how much time spent on conversations and …

parameters

title	required
token	true
contact_id	true

is case of success, response would be:

HTTP/1.1 200 OK
Content-Type: application/json
{
contact: { contact response object },
resources: {
"audio": {
"sent": [integer],
"recieved": [integer]
},
"file": {
"sent": [integer],
"recieved": [integer]
},
"pictures": {
"sent": [integer],
"recieved": [integer]
},
"videos": {
"sent": [integer],
"recieved": [integer]
},
"links": {
"sent": [integer],
"recieved": [integer]
},
"voices": {
"sent": [integer],
"recieved": [integer]
},
"links":{
"sent": [integer],
"recieved": [integer]
}
}
}

/autoReply CRUD

it’s a CRUD api bag. autoReply rules are useful to manage replies to contacts when they’re messaging the user. for example say hello to every hi from every contact. or reply 10:30 to when is it? from contact named josh

fields

title	required	type	description
pattern	true	string	what have to be recieved from contact to execute the reply
contact_id	true	integer	which contact have to send user a message to execute the reply
message	true	string	what have to be sent to contact when reply is executing

/messageQueue CRUD

message queue is a schedule for user to send a message to another contact in a certain time.

fields

title	required	type	description
contact_id	true	integer	contact that message have to be sent to him
message	true	string	message string that have to be sent to contact
time	true	integer	timestamp that say’s when have to send the message

/getThreadChart GET

get’s time’s spent on chating and conversation between user and a contact. informations are seperated by day’s and values are the times and chart contains the last 14 days

parameters

title	required
token	true
contact_id	true

is case of success, response would be:

HTTP/1.1 200 OK
Content-Type: application/json
{
code: 300
contact: { contact response object },
days: [
{
day: [the day. for example 1 means yesterday]
minutes: [time by minuts]
},
...
]
}

/autoDestruct CRUD

auto destruct messages would be sent to the contact and after a while after been seen, will be removed automaticaly.

fields

title	required	type	description
pattern	true	string	what have to be recieved from contact to execute the reply
contact_id	true	integer	which contact have to send user a message to execute the reply
message	true	string	what have to be sent to contact when reply is executing
time	true	string	seconds to be removed after been seen

/channel

/get GET

get user’s channels

parameters

title	required
token	true
offset	false
limit	false

in case of success response would be (channel)[#response-channel]

HTTP/1.1 200 OK
Content-Type: application/json
{
code: 400,
channels: [
{ channel response object },
...
]
}

/rate GET

rates a channel from 0 to 99

parameters

title	required
token	true
rate	true

/autoSeen CRUD

make a channel’s unread message, seen in time periods

fields

title	required	type	description
period	true	intger	minutes
contact_id	true	integer	which contact have to send user a message to execute the reply

/profile

/setMaxGoal

set the max goal of time spending online on minuates

parameters

title	required
token	true
goal	true

/getMaxGoal

get the max goal

parameters

title	required
token	true

in case of success response would be:

HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 400,
"goal": [integer]
}

/getTimeOnlineToday

parameters

title	required
token	true

in case of success response would be:

HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 400,
"time": [integer]
}

/getOnlineTimeLastWeek

gets the time spent last week online

parameters

title	required
token	true

in case of success response would be:

HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 400,
"times": [
{
day: [the day. for example 1 means yesterday]
minutes: [time by minuts]
},
...
]
}

Responses

code	category	description
200	auth	success in api call
211	auth	phone phone not found
212	auth	code code isn’t correct
213	auth	phone and code are incorrect
214	auth	token isn’t correct

Types

title	type	description
phone	string	international IR phone numbers like +989213829382
code	string	the code string sent to user’s telegram account for login progress
password	string	password used for two step verification
token	string	32 byte hashed string, session token string
user_id	integer	random 16byte string to refrence the session file in server
expire	integer	timestamp of the token expires
offset	integer	offset for pagination, default value is 0
limit	integer	limit for pagination, default value is 20
query	integer	query string. read more default value is 1
contact_id	integer	id of contact in database
rate	integer	number between 0 and 99
goal	integer	minutes

Slugs

field	rule	slug	message
phone	required	phone.required	phone is required
phone	format	phone.format	phone is invalid
code	required	code.required	code is required
code	invalid	code.invalid	code in invalid
session_id	required	session_id.required	session id is required
session_id	invalid	session_id.invalid	session_id is invalid
token	required	token.required	token in required
token	invalid	token.invalid	token is invalid invalid

query string

query is a SQL expression string and it’ll been validated so it’s injection clean. some of query example are:

• title LIKE '%tem' AND status = 1
• status = 1 OR status = 2
• (status <> 1 OR title LIKE '%article%') AND title LIKE '%a'

they’re grammatically checked and returns error code 400 on invalid and sql injection containing queries.

Response Models

response models are type of static json objects used to show variouse records in reponses such as contact, channel, bot and …
there are the models here:
Contact

{
	"id": [user id in database],
	"first_name": [contact first name],
	"last_name": [contact last name],
	"username": [contact username in telegram],
	"last_profile": [last profile picture of contact],
	"phone": [contact phone number],
	"picture": [contact picture]	
}

Channel

{
	"id": [channel id in database],
	"title": [channel title],
	"biography": [channel biography],
	"members": [channel members count],
	"rate":	[integer between 0 and 99],
	"picture": [channel picture]
}