Pajoohyar Core APIs Documention

The documentation provided describes how to work with all the APIs provided for the pajoohyar service. The pajoohyar API service is in the core project and you should go to the core project to view its source. The core project uses the Laravel framework. Its main database is MySQL. The dedicated service panel is located at this address. Here's how to connect to all APIs.

Response Types

There are several different types of response from the service that can be sent to the user. Each is separated by HTTP Status Code. Each is described below and an example is given below.

200: Successful Request

If the operation is successful. This answer will be returned. The data in response can be whatever the request is and the outcome of the operation.

HTTP Status Code: 200

Response:


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "[response object or array]"
}

201: Duplicate Successful Request

If the request has already been successfully resubmitted. This answer will be received. For example, the entity that was deleted in the previous request will resubmit the request.

HTTP Status Code: 201

Response:


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "[resopnse object or array]"
}

400: Invalid Request Error

This error occurs when the user has entered incorrect entries or has not entered them at all. Some APIs require specific inputs and must be followed.

HTTP Status Code: 400

Response:


xxxxxxxxxx
{
    "message": "you had some invalid parameters. please check them."
}

401: Authentication Error

This error occurs when the user has sent his session information incorrectly or not at all.

HTTP Status Code: 401

Response:


xxxxxxxxxx
{
    "message": "you are not authenticated."
}

402: Credit Error

This error occurs when the user does not have sufficient credentials to use the requested resources or entity.

HTTP Status Code: 402

Response:


xxxxxxxxxx
{
    "message": "you don't have enough credit for request entity/endpoint."
}

403: Permission Error

This error occurs when the user does not have access to the desired API. If the user has access to the desired API then it means that the user does not have access to the requested entity or resources.

HTTP Status Code: 403

Response:


xxxxxxxxxx
{
    "message": "you don't have permission to the requested entity/endpoint."
}

404: Not Found Error

This error occurs when the user has the wrong address or endpoint requested. If the user has entered the endpoint correctly then there is no resource or entity requested. Another error is that the resources or resources requested by the user are hidden from view.

HTTP Status Code: 404

Response:


xxxxxxxxxx
{
    "message": "your requested endpoint/entity not found."
}

405: Bad Method Error

This error occurs when the verb user has sent the request incorrectly. For example the verb is POST but the user sent GET.

HTTP Status Code: 405

Response:


xxxxxxxxxx
{
    "message": "you have used an invalid verb in your request. please check it."
}

Authentication

Currently login and registration is only possible with a passport. But in addition, logging in through INoor and Google is also considered. Login and registration via passport uses the eargonomic technique. User authentication via email or mobile number is not considered. Some APIs marked with Auth require user login information in their Header. This requires the user to use the Login or Register APIs first and then request ACCESS_TOKEN in the header. As follows:


xxxxxxxxxx
Authorization: bearer ACCESS_TOKEN

All requests must respect which pajoohyar product was sent from. Therefore, all requests in the header must contain a Context value. Each researcher product has its own separate context. For example Context of online library is onlib, or Context of online citation is cite. In other words, the following value should also be added to the header of all requests:


xxxxxxxxxx
Context: CONTEXT_OF_CLIENT_PRODUCT

all request verbs are POST so don't bother yourself to change to verbs. all are POST and all Content-Type are multipart/form-data.

Here are its APIs:

/auth/passport/register

Parameters

name	type	description	example
username	string	require, max: 32, min: 6	amiri1368
password	string	require, max: 32, min: 6	amiri1368
first_name	string	require, max: 32	amir
last_name	string	require, max: 32	jadidi
email	string	require, email address	amiri1368@yahoo.com
avatar	file	image type, max size: 2MB	-
gender	numeric	1 for male and 2 for female	1

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "access_token": "BEARER_ACCESS_TOKEN",
        "expires_at": "TIMESTAMPS",
        "user": "[User Model]"
    }
}

/auth/passport/login

Parameters

name	type	description	example
username	string	max: 32, min: 6	amiri1368
password	string	max: 32, min: 6	amiri1368

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "access_token": "BEARER_ACCESS_TOKEN",
        "expires_at": "TIMESTAMPS",
        "user": "[User Model]"
    }
}

/auth/passport/profile/show (`auth`)

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "[User Model]"
}

/auth/passport/profile/update (`auth`)

Parameters

name	type	description	example
username	string	require, max: 32, min: 6	amiri1368
password	string	require, max: 32, min: 6	amiri1368
first_name	string	require, max: 32	amir
last_name	string	require, max: 32	jadidi
email	string	require, email address	amiri1368@yahoo.com
avatar	file	image type, max size: 2MB	-
gender	numeric	1 for male and 2 for female	1

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "[User Model]"
}

/auth/passport/logout (`auth`)

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

Collections

/collections/search/privates (`auth`)

Parameters

name	type	description	example
collection_id	numeric	unique target collection id	342
query	string	part of title or description	"something"
title	string	part of title	"foo"
description	string	part of description	"bar"
tags	[string]	some of tags that collection owns	["foo", "bar"]
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "Collection Model",
            "...",
            "Collection Model",
        ]
    }
}

/collections/search/publics

Parameters

name	type	description	example
collection_id	numeric	unique target collection id	342
query	string	part of title or description	"something"
title	string	part of title	"foo"
description	string	part of description	"bar"
tags	[numeric]	some of tags that collection owns	[3, 5]
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "Collection Model",
            "...",
            "Collection Model",
        ]
    }
}

/collections/create (`auth`)

Parameters

name	type	description	example
title	string	max: 128	"foo"
description	string	max: 1024	"bar"
tags	[numeric]	array of tags by id	[1, 5]
logo	file	max size: 5MB	-
cover	file	max size: 10MB	-

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Collection Model",
}

/collections/update (`auth`)

Parameters

name	type	description	example
collection_id	unique id of collection	83
title	string	max: 128	"foo"
description	string	max: 1024	"bar"
tags	[numeric]	array of tags by id	[1, 5]
logo	file	max size: 5MB	-
cover	file	max size: 10MB	-

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Collection Model",
}

/collections/remove (`auth`)

Parameters

name	type	description	example
collection_id	numeric	unique target collection id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/collections/subscribe (`auth`)

Parameters

name	type	description	example
collection_id	numeric	unique target collection id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/collections/unsubscripe (`auth`)

Parameters

name	type	description	example
collection_id	numeric	unique target collection id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

Collection Membership

/collections/membership/create (`auth`)

Parameters

name	type	description	example
user_id	numeric	unique target user id	342
access	numeric	1: owner, 2: editor, 3: visitor	2

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Collection Membership Model"
}

/collections/membership/update (`auth`)

Parameters

name	type	description	example
membership_id	numeric	unique target membership id	342
access	numeric	1: owner, 2: editor, 3: visitor	2

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Collection Membership Model"
}

/collections/membership/remove (`auth`)

Parameters

name	type	description	example
membership_id	numeric	unique target membership id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/collections/membership/submit-request (`auth`)

Parameters

name	type	description	example
collection_id	numeric	unique target collection id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

Items

/items/search/privates (`auth`)

Parameters

name	type	description	example
item_id	numeric	unique target item id	342
collection_id	numeric	unique collection id that owns item	43
query	string	part of title or description	"something"
title	string	part of title	"foo"
description	string	part of description	"bar"
tags	[string]	some of tags that item owns	["foo", "bar"]
type	numeric	type id of item	25 (as newspaper article)
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "Item Model",
            "...",
            "Item Model",
        ]
    }
}

/items/search/publics

Parameters

name	type	description	example
item_id	numeric	unique target item id	342
collection_id	numeric	unique collection id that owns item	43
query	string	part of title or description	"something"
title	string	part of title	"foo"
description	string	part of description	"bar"
tags	[string]	some of tags that item owns	["foo", "bar"]
type	numeric	type id of item	25 (as newspaper article)
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "Item Model",
            "...",
            "Item Model",
        ]
    }
}

/items/create (`auth`)

Parameters

name	type	description	example
type	numeric	type id of item	25 (as newspaper article)
collection_id	numeric	unique collection id	434
title	string	max: 128	"foo"
description	string	max: 1024	"bar"
tags	[numeric]	array of tags by id	[1, 5]
fields	[{"key": number, "value": string}]	fields of item	[]

Responses


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Item Model"
}

/items/update (`auth`)

Parameters

name	type	description	example
item_id	numeric	target item id	34
type	numeric	type id of item	25 (as newspaper article)
collection_id	numeric	unique collection id	434
title	string	max: 128	"foo"
description	string	max: 1024	"bar"
tags	[numeric]	array of tags by id	[1, 5]
fields	[{"key": number, "value": string}]	fields of item	[]

Responses


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Item Model"
}

/items/remove (`auth`)

Parameters

name	type	description	example
item_id	numeric	unique target item id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

Notes

/notes/search

Parameters

name	type	description	example
note_id	numeric	unique target note id	483
item_id	numeric	unique target item id that owns note	342
collection_id	numeric	unique collection id that owns note	43
owner_id	numeric	unique user id that worte the comment	443
query	string	part of title or body	"something"
title	string	part of title	"foo"
body	string	part of body	"bar"
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "Note Model",
            "...",
            "Note Model",
        ]
    }
}

/notes/create (`auth`)

Parameters

name	type	description	example
title	string	max: 128	"something"
body	string	max: 1024	"hello bar"
target_type	numeric	1 => collection, 2 => item	1
target_id	numeric	based on target_type	43

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Note Model"
}

/notes/update (`auth`)

Parameters

name	type	description	example
note_id	numeric	unique target note id	434
title	string	max: 128	"something"
body	string	max: 1024	"hello bar"
target_type	numeric	1 => collection, 2 => item	1
target_id	numeric	based on target_type	43

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Note Model"
}

/notes/remove (`auth`)

Parameters

name	type	description	example
note_id	numeric	unique target note id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/notes/publish (`auth`)

Parameters

name	type	description	example
note_id	numeric	unique target note id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/notes/unpublish (`auth`)

Parameters

name	type	description	example
note_id	numeric	unique target note id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

Comments

/comments/search

Parameters

name	type	description	example
comment_id	numeric	unique target comment id	483
item_id	numeric	unique target item id that owns comment	342
collection_id	numeric	unique collection id that owns comment	43
note_id	numeric	unique note id that owns comment	43
owner_id	numeric	unique user id that worte the comment	443
reply_id	numeric	unique user id that comment is replied to	445
body	string	part of body	"bar"
published	numeric	1 => pending, 2 => published, 3 => unpublished	1
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "Comment Model",
            "...",
            "Comment Model",
        ]
    }
}

/comments/submit (`auth`)

Parameters

name	type	description	example
target_type	numeric	1 => collection, 2 => item, 3 => note	2
target_id	numeric	unique target id based on target_type	32
reply_to	numeric	unique id of target comment, if replay id is entered then target_type and target_id have to be null	445
body	string	comment body, max: 512	"oh! this is great."

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Comment Model"
}

/comments/update (`auth`)

Parameters

name	type	description	example
comment_id	numeric	unique comment id	443
target_type	numeric	1 => collection, 2 => item, 3 => note	2
target_id	numeric	unique target id based on target_type	32
reply_to	numeric	unique id of target comment, if replay id is entered then target_type and target_id have to be null	445
body	string	comment body, max: 512	"oh! this is great."

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Comment Model"
}

/comments/remove (`auth`)

Parameters

name	type	description	example
comment_id	numeric	unique target comment id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/comments/publish (`auth`)

Parameters

name	type	description	example
comment_id	numeric	unique target comment id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/comments/unpublish (`auth`)

Parameters

name	type	description	example
comment_id	numeric	unique target comment id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

Messages

/messages/send (`auth`)

Parameters

name	type	description	example
title	string	max: 128	"hey budy!"
body	string	max: 1024	"let's be friend."
recipients	[numeric]	unique id of users	[3, 43, 1]
attachments	[file]	max size of each file < 5 MB	-

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": "Message Model"
}

/messages/search (`auth`)

Parameters

name	type	description	example
type	numeric	1 => me as sender, 2 => me as a recipient	1
sender_id	numeric	unique target user id	23
recipient_id	numeric	unique target user id	45
query	string	part of title or body	"h"
title	string	part of title	"h"
body	string	part of body	"h"
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Success Response


xxxxxxxxxx
    "message": "operation was successfull.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "Message Model",
            "...",
            "Message Model",
        ]
    }

Users (`auth`)

/users/search (`auth`)

Parameters

name	type	description	example
first_name	string	part of first name	"ali"
last_name	string	part of last name	"ali"
full_name	string	part of full name	"ali"
user_ud	numeric	target user id	324
offset	numeric	offset of results	0
limit	numeric	limit of results	10

Response


xxxxxxxxxx
{
    "message": "operation was successfull.",
    "data": {
        "total": "NUMERIC",
        "offset": "NUMERIC",
        "limit": "NUMERIC",
        "results": [    
            "User Model",
            "...",
            "User Model",
        ]
    }
}

/users/follow (`auth`)

Parameters

name	type	description	example
user_id	numeric	unique target user id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

/users/unfollow (`auth`)

Parameters

name	type	description	example
user_id	numeric	unique target user id	342

Success Response


xxxxxxxxxx
{
    "message": "operation was successful.",
    "data": null
}

Logs

/logs/send

Parameters

name	type	description	example
action	string	max: 32	"visited"
sub_action	string	max: 64	"null"
value	string	max: 128	"main_page"
info	json object	max: 1024	"{}"

Response


xxxxxxxxxx
{
    "message": "operation was successfull.",
    "data": "Log Model",
}

Pajoohyar Core APIs Documention

Response Types

200: Successful Request

201: Duplicate Successful Request

400: Invalid Request Error

401: Authentication Error

402: Credit Error

403: Permission Error

404: Not Found Error

405: Bad Method Error

Authentication

/auth/passport/register

Parameters

Success Response

/auth/passport/login

Parameters

Success Response

/auth/passport/profile/show (auth)

Success Response

/auth/passport/profile/update (auth)

Parameters

Success Response

/auth/passport/logout (auth)

Success Response

Collections

/collections/search/privates (auth)

Parameters

Success Response

/collections/search/publics

Parameters

Success Response

/collections/create (auth)

Parameters

Success Response

/collections/update (auth)

Parameters

Success Response

/collections/remove (auth)

Parameters

Success Response

/collections/subscribe (auth)

Parameters

Success Response

/collections/unsubscripe (auth)

Parameters

Success Response

Collection Membership

/collections/membership/create (auth)

Parameters

Success Response

/collections/membership/update (auth)

Parameters

Success Response

/collections/membership/remove (auth)

Parameters

Success Response

/collections/membership/submit-request (auth)

Parameters

Success Response

Items

/items/search/privates (auth)

Parameters

Success Response

/items/search/publics

Parameters

Success Response

/items/create (auth)

Parameters

Responses

/items/update (auth)

Parameters

Responses

/items/remove (auth)

Parameters

Success Response

Notes

/notes/search

Parameters

Success Response

/notes/create (auth)

/auth/passport/profile/show (`auth`)

/auth/passport/profile/update (`auth`)

/auth/passport/logout (`auth`)

/collections/search/privates (`auth`)

/collections/create (`auth`)

/collections/update (`auth`)

/collections/remove (`auth`)

/collections/subscribe (`auth`)

/collections/unsubscripe (`auth`)

/collections/membership/create (`auth`)

/collections/membership/update (`auth`)

/collections/membership/remove (`auth`)

/collections/membership/submit-request (`auth`)

/items/search/privates (`auth`)

/items/create (`auth`)

/items/update (`auth`)

/items/remove (`auth`)

/notes/create (`auth`)

/notes/update (`auth`)

/notes/remove (`auth`)

/notes/publish (`auth`)

/notes/unpublish (`auth`)

/comments/submit (`auth`)

/comments/update (`auth`)

/comments/remove (`auth`)

/comments/publish (`auth`)

/comments/unpublish (`auth`)

/messages/send (`auth`)

/messages/search (`auth`)

Users (`auth`)

/users/search (`auth`)

/users/follow (`auth`)

/users/unfollow (`auth`)