---

---

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

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
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:

{
	"hits": [count of results based on query, offset and limit],
	"matches": [count of results just based on query],
	"results": [
		{contact response object}
	]
}

Responses

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

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

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],
}