Skip to content

Instantly share code, notes, and snippets.

@mr-exception

mr-exception/ZhoZho

Created March 5, 2018 08:07
Show Gist options
  • Save mr-exception/7a3c7fafbd824ed21586577ac9cbce53 to your computer and use it in GitHub Desktop.
Save mr-exception/7a3c7fafbd824ed21586577ac9cbce53 to your computer and use it in GitHub Desktop.
Download ZIP
ZhoZho
Raw
ZhoZho
<h1 id="zhozho-project-api-documention">ZhoZho project API Documention</h1>
<p>APIs are using HTTP/1.2 protocol and best practice of rest Apis in 2015<br>
we have to devlare api responses schema before listing them. all the apis are in <code>HTTP1/1</code> requests are in variouse verbs such as <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code> and…, input parameters are from-data to handle the file uploading too. responses are in json/text schema</p>
<h4 id="http-response-codes">HTTP response codes</h4>
<p>HTTP response codes are all in standard of <a href="https://httpstatuses.com/">HTTP1/1</a></p>
<h4 id="response-codes">Response Codes</h4>
<p>Response codes are included in some categories shown in table blew:</p>
<table>
<thead>
<tr>
<th>code</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>100</td>
<td>success code in any api result</td>
</tr>
<tr>
<td>101</td>
<td>missing a parameter in api inputs</td>
</tr>
<tr>
<td>2XX</td>
<td>error codes that can happen in auth apis</td>
</tr>
<tr>
<td>3XX</td>
<td>error codes that can happen in contact apis</td>
</tr>
<tr>
<td>4XX</td>
<td>error codes that can happen in channel apis</td>
</tr>
<tr>
<td>5XX</td>
<td>error codes that can happen in profile apis</td>
</tr>
</tbody>
</table><h5 id="code-100">Code 100</h5>
<p>this response happens when everything is ok and we get the success message from service, so the response message would be:</p>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 100,
"message": [some success message]
}
</code></pre>
<h5 id="code-101">Code 101</h5>
<p>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:</p>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 101,
"errors": [
{
"name": [parameter name 1]
"message": [error message 1]
}
...
]
}
</code></pre>
<h5 id="code-2xx-3xx-4xx-5xx">Code 2XX, 3XX, 4XX, 5XX</h5>
<p>this response codes are for various parts of apis. but all of them have a certain schema for response test. that’s written blew:</p>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json
{
code: XXX
message: [error message]
}
</code></pre>
<blockquote>
<p><code>note:</code> 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.</p>
</blockquote>
<h4 id="api-lists">API lists</h4>
<p>all apis are seperated in two categories:<br>
<strong>Crud APIs</strong> 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:</p>
<table>
<thead>
<tr>
<th>End Point</th>
<th>Verb</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td>/autoReply</td>
<td>GET</td>
<td>retrive</td>
</tr>
<tr>
<td>/autoReply</td>
<td>PUT</td>
<td>create</td>
</tr>
<tr>
<td>/autoReply/[id]</td>
<td>UPDATE</td>
<td>update</td>
</tr>
<tr>
<td>/autoReply/[id]</td>
<td>DELETE</td>
<td>delete</td>
</tr>
</tbody>
</table><h6 id="retrive">Retrive</h6>
<p>retrive action get a list of records in response, the verb is <code>GET</code> and there are some default parameters then. first parameter are <code>offset</code> and then <code>limit</code> for records pagination. last parameter in <a href="#query-string">query</a> for searching in records.</p>
<h6 id="create">Create</h6>
<p>create action get’s the required fields in parameter and stores the record in database. all queries are the fields for that document.</p>
<h6 id="update">Update</h6>
<p>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, <code>101</code> error’ll return.<br>
update end-point is <code>/autoReply/[id]</code> like <code>autoReply/2</code> that updates the record by id = 2</p>
<h6 id="delete">Delete</h6>
<p>delete action get’s the record id in url parameter and removes it. if record not found <code>404</code> would be returned by HTTP Response Code <code>404</code>:</p>
<pre><code>HTTP/1.1 404 Not Found
Content-Type: application/json
{
code: 404,
message: "record not found"
}
</code></pre>
<p>if record found, would be removed from database and a response in HTTP Response Code <code>200</code>:</p>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json
{
code: 200,
message: "record removed successfully",
record: { record object }
}
</code></pre>
<p><strong>Action APIs</strong> 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.</p>
<table>
<thead>
<tr>
<th>Category</th>
<th>End Point</th>
<th>Verb</th>
<th>Title</th>
</tr>
</thead>
<tbody>
<tr>
<td>auth</td>
<td><a href="#sendCode">sendCode</a></td>
<td>POST</td>
<td>sends code to telegram account</td>
</tr>
<tr>
<td>auth</td>
<td>checkCode</td>
<td>POST</td>
<td>check the code sent to telegram</td>
</tr>
<tr>
<td>auth</td>
<td>login</td>
<td>POST</td>
<td>login the user in application</td>
</tr>
<tr>
<td>auth</td>
<td>logout</td>
<td>POST</td>
<td>logout the user from applocation</td>
</tr>
<tr>
<td>auth</td>
<td>removeSession</td>
<td>POST</td>
<td>remove the user’s session</td>
</tr>
<tr>
<td>contacts</td>
<td>getContacts</td>
<td>GET</td>
<td>get user’s contacts</td>
</tr>
<tr>
<td>contacts</td>
<td>getNoisyContacts</td>
<td>GET</td>
<td>get user’s noisy channels</td>
</tr>
<tr>
<td>contacts</td>
<td>getBestContacts</td>
<td>GET</td>
<td>get user’s best contacts</td>
</tr>
<tr>
<td>contacts</td>
<td>analyzeContacts</td>
<td>GET</td>
<td>analyze a contact and return response</td>
</tr>
<tr>
<td>contacts</td>
<td>getThreadChart</td>
<td>GET</td>
<td>get a volume chart for a thread</td>
</tr>
<tr>
<td>contacts</td>
<td>autoReply</td>
<td>CRUD</td>
<td>manage all auto replies</td>
</tr>
<tr>
<td>contacts</td>
<td>messageQueue</td>
<td>CRUD</td>
<td>manage all message queues</td>
</tr>
<tr>
<td>contacts</td>
<td>autoDestruct</td>
<td>CRUD</td>
<td>manage all auto destructs</td>
</tr>
<tr>
<td>channels</td>
<td>getChannels</td>
<td>GET</td>
<td>get all channels that user’s joined</td>
</tr>
<tr>
<td>channels</td>
<td>rate</td>
<td>PUT</td>
<td>rate a channel</td>
</tr>
<tr>
<td>channels</td>
<td>autoSeen</td>
<td>CRUD</td>
<td>manage all auto seen periods</td>
</tr>
<tr>
<td>profile</td>
<td>setMaxGoal</td>
<td>PUT</td>
<td>set max online time goal</td>
</tr>
<tr>
<td>profile</td>
<td>getMaxGoal</td>
<td>GET</td>
<td>get max online time goal</td>
</tr>
<tr>
<td>profile</td>
<td>getOnlineTimeToday</td>
<td>GET</td>
<td>get time spent online last 24 hours</td>
</tr>
<tr>
<td>profile</td>
<td>getOnlineTimeLastWeek</td>
<td>GET</td>
<td>get time spent online last 7 days</td>
</tr>
</tbody>
</table><h3 id="a-idautha-auth"><a id="auth"></a> auth</h3>
<h4 id="a-idsendcodeasendcode-post"><a id="sendCode"></a>sendCode <code>POST</code></h4>
<p>sends the code to user’s telegram account and user have to enter it in app.</p>
<h4 id="parameters">parameters</h4>
<table>
<thead>
<tr>
<th>title</th>
<th>required</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#type-phone">phone</a></td>
<td>true</td>
</tr>
</tbody>
</table><h4 id="a-idcheckcodeacheckcode-post"><a id="checkCode"></a>checkCode <code>POST</code></h4>
<p>checks the code that user got in telegram account</p>
<h4 id="parametes">parametes</h4>
<table>
<thead>
<tr>
<th>title</th>
<th>required</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#type-phone">phone</a></td>
<td>true</td>
</tr>
<tr>
<td><a href="#type-code">code</a></td>
<td>true</td>
</tr>
</tbody>
</table><p>in case of success for this API returns the a random 16byte string named <a href="#session_id">session_id</a></p>
<h4 id="a-idloginalogin-post"><a id="login"></a>login <code>POST</code></h4>
<p>login the user into application by a new refreshed token</p>
<h4 id="parameters-1">parameters</h4>
<table>
<thead>
<tr>
<th>title</th>
<th>required</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#type-phone">phone</a></td>
<td>true</td>
</tr>
<tr>
<td><a href="#type-session_id">session_id</a></td>
<td>true</td>
</tr>
</tbody>
</table><p>on success response contains <a href="#type-token">token</a> field and <a href="#type-expire">expire</a>.</p>
<h4 id="a-idlogoutalogout-post"><a id="logout"></a>logout <code>POST</code></h4>
<p>logout the user and terminate the user’s session on application</p>
<h4 id="parameters-2">parameters</h4>
<table>
<thead>
<tr>
<th>title</th>
<th>required</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#type-token">token</a></td>
<td>true</td>
</tr>
</tbody>
</table><h4 id="a-idterminateaterminatesession-post"><a id="terminate"></a>terminateSession <code>POST</code></h4>
<p>terminates the telegram session for application. after calling this method successfully, user have to login again via telegram to use the application services</p>
<h4 id="parameters-3">parameters</h4>
<table>
<thead>
<tr>
<th>title</th>
<th>required</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#type-token">token</a></td>
<td>true</td>
</tr>
</tbody>
</table><h3 id="a-idcontactsa-contacts"><a id="contacts"></a> contacts</h3>
<h4 id="a-idgeta-get-get"><a id="get"></a> get <code>GET</code></h4>
<p>get’s all contacts of user from telegram account</p>
<h4 id="parameters-4">parameters</h4>
<table>
<thead>
<tr>
<th>title</th>
<th>required</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#type-offset">offset</a></td>
<td>false</td>
</tr>
<tr>
<td><a href="#type-limit">limit</a></td>
<td>false</td>
</tr>
<tr>
<td><a href="#type-query">query</a></td>
<td>false</td>
</tr>
</tbody>
</table><p>in case of success call for <code>get</code> response contains a field names results and items are <a href="#response-contact">contact</a> would be a json text like:</p>
<pre><code>{
"hits": [count of results based on query, offset and limit],
"matches": [count of results just based on query],
"results": [
{contact response object}
]
}
</code></pre>
<h3 id="responses">Responses</h3>
<table>
<thead>
<tr>
<th>code</th>
<th>category</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>auth</td>
<td><code>success</code> in api call</td>
</tr>
<tr>
<td>211</td>
<td>auth</td>
<td><a href="#type-phone">phone</a> phone not found</td>
</tr>
<tr>
<td>212</td>
<td>auth</td>
<td><a href="#type-code">code</a> code isn’t valid</td>
</tr>
<tr>
<td>213</td>
<td>auth</td>
<td><a href="#type-phone">phone</a> and <a href="#type-code">code</a> are incorrect</td>
</tr>
<tr>
<td>214</td>
<td>auth</td>
<td><a href="#type-token">token</a> is invalid</td>
</tr>
</tbody>
</table><h2 id="types">Types</h2>
<table>
<thead>
<tr>
<th>title</th>
<th>type</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a id="type-phone"></a>phone</td>
<td>string</td>
<td>international IR phone numbers like <code>+989213829382</code></td>
</tr>
<tr>
<td><a id="type-code"></a>code</td>
<td>string</td>
<td>the code string sent to user’s telegram account for login progress</td>
</tr>
<tr>
<td><a id="type-password"></a>password</td>
<td>string</td>
<td>password used for two step verification</td>
</tr>
<tr>
<td><a id="type-token"></a>token</td>
<td>string</td>
<td>32 byte hashed string, session token string</td>
</tr>
<tr>
<td><a id="type-session_id"></a>user_id</td>
<td>integer</td>
<td>random 16byte string to refrence the session file in server</td>
</tr>
<tr>
<td><a id="type-expire"></a>expire</td>
<td>integer</td>
<td>timestamp of the token expires</td>
</tr>
<tr>
<td><a id="type-offset"></a>offset</td>
<td>integer</td>
<td>offset for pagination, default value is 0</td>
</tr>
<tr>
<td><a id="type-limit"></a>limit</td>
<td>integer</td>
<td>limit for pagination, default value is 20</td>
</tr>
<tr>
<td><a id="type-query"></a>query</td>
<td>integer</td>
<td>query string. <a href="#query-string">read more</a> default value is <code>1</code></td>
</tr>
</tbody>
</table><h3 id="a-idquery-stringaquery-string"><a id="query-string"></a>query string</h3>
<p>query is a SQL expression string and it’ll been validated so it’s injection clean. some of query example are:</p>
<ul>
<li><code>title LIKE '%tem' AND status = 1</code></li>
<li><code>status = 1 OR status = 2</code></li>
<li><code>(status &lt;&gt; 1 OR title LIKE '%article%') AND title LIKE '%a'</code></li>
</ul>
<p>they’re grammatically checked and returns error code <code>400</code> on invalid and sql injection containing queries.</p>
<h2 id="response-models">Response Models</h2>
<p>response models are type of static json objects used to show variouse records in reponses such as contact, channel, bot and …<br>
there are the models here:<br>
<strong><a id="response-contact"></a>Contact</strong></p>
<pre><code>{
"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],
}
</code></pre>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment