REST API Usage

ShahiAssist provides a comprehensive REST API for integrating with external applications, automating workflows, and building custom interfaces.

API Overview

Base URL

`
https://yoursite.com/wp-json/shahi-assist/v1/
`

Authentication

The API supports WordPress Application Passwords and OAuth authentication.

Application Passwords

1. Go to Users → Profile in WordPress admin
2. Scroll to Application Passwords section
3. Create a new password
4. Use username and password in API requests

Basic Auth Example


`bash
curl -u “username:application_password” https://yoursite.com/wp-json/shahi-assist/v1/tickets
`

Tickets Endpoints


List Tickets


`
GET /wp-json/shahi-assist/v1/tickets
`

Parameters:

• status: Filter by status (open, closed, pending)
• author: Filter by author ID
• search: Search term
• page: Page number (default: 1)
• per_page: Items per page (default: 10, max: 100)
• orderby: Sort field (date, title, status)
• order: Sort order (asc, desc)

Example:
`bash
curl -u “user:pass” “https://yoursite.com/wp-json/shahi-assist/v1/tickets?status=open&per_page=5”
`

Response:
`json
{
“tickets”: [
{
“id”: 123,
“title”: “Login issue”,
“status”: “open”,
“author”: 5,
“date”: “2023-11-27T10:00:00”,
“link”: “https://yoursite.com/ticket/login-issue/”
}
],
“total”: 25,
“pages”: 5
}
`

Get Single Ticket


`
GET /wp-json/shahi-assist/v1/tickets/{id}
`

Example:
`bash
curl -u “user:pass” https://yoursite.com/wp-json/shahi-assist/v1/tickets/123
`

Response:
`json
{
“id”: 123,
“title”: “Login issue”,
“content”: “I can’t log in to my account”,
“status”: “open”,
“author”: 5,
“assigned_agent”: 10,
“date”: “2023-11-27T10:00:00”,
“modified”: “2023-11-27T11:00:00”,
“replies”: [
{
“id”: 456,
“content”: “Please try resetting your password”,
“author”: 10,
“date”: “2023-11-27T10:30:00”
}
],
“custom_fields”: {
“priority”: “high”,
“product”: “web_app”
}
}
`

Create Ticket


`
POST /wp-json/shahi-assist/v1/tickets
`

Required Parameters:

• title: Ticket title
• content: Ticket description

Optional Parameters:

• status: Initial status
• assigned_agent: Agent ID to assign
• custom_fields: Object of custom field values

Example:
`bash
curl -u “user:pass” -X POST https://yoursite.com/wp-json/shahi-assist/v1/tickets \
-H “Content-Type: application/json” \
-d ‘{
“title”: “New feature request”,
“content”: “Please add dark mode”,
“custom_fields”: {
“priority”: “medium”,
“category”: “feature_request”
}
}’
`

Update Ticket


`
PUT /wp-json/shahi-assist/v1/tickets/{id}
`

Parameters:

• Any updatable field (title, content, status, assignedagent, customfields)

Example:
`bash
curl -u “user:pass” -X PUT https://yoursite.com/wp-json/shahi-assist/v1/tickets/123 \
-H “Content-Type: application/json” \
-d ‘{“status”: “closed”, “assigned_agent”: 15}’
`

Delete Ticket


`
DELETE /wp-json/shahi-assist/v1/tickets/{id}
`

Example:
`bash
curl -u “user:pass” -X DELETE https://yoursite.com/wp-json/shahi-assist/v1/tickets/123
`

Knowledge Base Endpoints


List Articles


`
GET /wp-json/shahi-assist/v1/articles
`

Parameters:

• category: Category ID or slug
• search: Search term
• author: Author ID
• status: publish, draft, etc.
• page, per_page, orderby, order: Same as tickets

Get Single Article


`
GET /wp-json/shahi-assist/v1/articles/{id}
`

Create Article


`
POST /wp-json/shahi-assist/v1/articles
`

Required: title, content

Update Article


`
PUT /wp-json/shahi-assist/v1/articles/{id}
`

Delete Article


`
DELETE /wp-json/shahi-assist/v1/articles/{id}
`

User Management Endpoints


List Users


`
GET /wp-json/shahi-assist/v1/users
`

Parameters:

• role: supportagent, supportmanager
• search: Search by name/email

Get User Details


`
GET /wp-json/shahi-assist/v1/users/{id}
`

Update User


`
PUT /wp-json/shahi-assist/v1/users/{id}
`

Updatable fields: assigned tickets, role-specific data

Advanced API Features


Filtering and Searching


`bash

Complex filtering


curl -u “user:pass” “https://yoursite.com/wp-json/shahi-assist/v1/tickets?status=open&assignedagent=10&customfields[priority]=high”
`

Pagination


`bash

Get second page with 20 items


curl -u “user:pass” “https://yoursite.com/wp-json/shahi-assist/v1/tickets?page=2&per_page=20”
`

Sorting


`bash

Sort by date descending


curl -u “user:pass” “https://yoursite.com/wp-json/shahi-assist/v1/tickets?orderby=date&order=desc”
`

Bulk Operations


`bash

Update multiple tickets


curl -u “user:pass” -X POST https://yoursite.com/wp-json/shahi-assist/v1/tickets/bulk \
-H “Content-Type: application/json” \
-d ‘{
“tickets”: [123, 124, 125],
“action”: “update_status”,
“status”: “closed”
}’
`

Rate Limiting


• Authenticated requests: 100 per hour per user
• Unauthenticated requests: 10 per hour per IP
• Headers returned:

– X-RateLimit-Limit: Total allowed
– X-RateLimit-Remaining: Remaining requests
– X-RateLimit-Reset: Reset time (Unix timestamp)

Error Handling


Common HTTP Status Codes


• 200: Success
• 201: Created
• 400: Bad Request (validation error)
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Too Many Requests (rate limited)
• 500: Internal Server Error

Error Response Format


`json
{
“code”: “invalidticketid”,
“message”: “Invalid ticket ID provided”,
“data”: {
“status”: 400
}
}
`

SDKs and Libraries


PHP SDK


`php
require ‘shahi-assist-sdk.php’;

$sdk = new ShahiAssistSDK(‘https://yoursite.com’, ‘username’, ‘password’);

// Get tickets
$tickets = $sdk->getTickets([‘status’ => ‘open’]);

// Create ticket
$newTicket = $sdk->createTicket([
‘title’ => ‘API Test’,
‘content’ => ‘Testing API integration’
]);
`

JavaScript SDK


`javascript
import ShahiAssist from ‘shahi-assist-js-sdk’;

const client = new ShahiAssist({
baseURL: ‘https://yoursite.com/wp-json/shahi-assist/v1/’,
auth: {
username: ‘user’,
password: ‘app_password’
}
});

// Async/await example
async function getOpenTickets() {
try {
const tickets = await client.tickets.list({ status: ‘open’ });
console.log(tickets);
} catch (error) {
console.error(error);
}
}
`

Python SDK


`python
from shahiassistsdk import ShahiAssistClient

client = ShahiAssistClient(
base_url=’https://yoursite.com/wp-json/shahi-assist/v1/’,
username=’user’,
password=’app_password’
)

Get tickets


tickets = client.tickets.list(status=’open’)

Create ticket


new_ticket = client.tickets.create({
‘title’: ‘Python API Test’,
‘content’: ‘Testing Python SDK’
})
`

Webhooks Integration


Register Webhook


`bash
curl -u “user:pass” -X POST https://yoursite.com/wp-json/shahi-assist/v1/webhooks \
-H “Content-Type: application/json” \
-d ‘{
“url”: “https://myapp.com/webhook”,
“events”: [“ticket.created”, “ticket.status_changed”],
“secret”: “webhook_secret”
}’
`

Handle Webhook


`php
// webhook-handler.php
$payload = jsondecode(fileget_contents(‘php://input’), true);
$signature = $SERVER[‘HTTPXSHAHIASSIST_SIGNATURE’];

if (verifysignature($payload, $signature, ‘webhooksecret’)) {
switch ($payload[‘event’]) {
case ‘ticket.created’:
// Handle new ticket
break;
case ‘ticket.status_changed’:
// Handle status change
break;
}
}
`

Security Best Practices


Use HTTPS


Always use HTTPS for API requests to encrypt data in transit.

Validate Input


Server-side validation is crucial:
`php
addfilter(‘shahiassistrestpreinsertticket’, function($prepared_post, $request) {
if (empty($prepared_post[‘title’])) {
return new WPError(‘missingtitle’, ‘Title is required’, [‘status’ => 400]);
}
return $prepared_post;
}, 10, 2);
`

Permission Checks


Ensure proper permissions for API actions:
`php
addfilter(‘shahiassistrestticket_permissions’, function($permissions, $request) {
if ($request->get_method() === ‘DELETE’) {
return currentusercan(‘delete_tickets’);
}
return $permissions;
}, 10, 2);
`

API Key Rotation


Regularly rotate application passwords and API keys.

Performance Optimization


Caching


Implement caching for frequently accessed data:
`php
addfilter(‘shahiassistrestcache_tickets’, function($cache, $request) {
$cachekey = ‘tickets‘ . md5(serialize($request->get_params()));
$cached = wpcacheget($cachekey, ‘shahiassist_api’);

if ($cached !== false) {
return $cached;
}

// Cache for 5 minutes
wpcacheset($cachekey, $cache, ‘shahiassist_api’, 300);
return $cache;
});
`

Pagination


Always use pagination for large datasets to avoid performance issues.

Selective Fields


Use _fields parameter to return only needed data:
`bash
curl -u “user:pass” “https://yoursite.com/wp-json/shahi-assist/v1/tickets?_fields=id,title,status”
`

Testing and Debugging


API Testing Tools


• Postman
• Insomnia
• curl
• HTTPie

Debug Mode


Enable debug logging:
`php
addfilter(‘shahiassistapidebug’, ‘_returntrue’);
`

Logging Requests


`php
addaction(‘shahiassistrestapi_request’, function($request, $response) {
errorlog(‘API Request: ‘ . $request->getmethod() . ‘ ‘ . $request->get_route());
if (iswperror($response)) {
errorlog(‘API Error: ‘ . $response->geterror_message());
}
}, 10, 2);
`

Common Issues and Solutions


Authentication Problems


• Verify application password is correct
• Check user has proper permissions
• Ensure HTTPS is used

CORS Issues


Add CORS headers for frontend applications:
`php
addaction(‘restapi_init’, function() {
header(‘Access-Control-Allow-Origin: https://myapp.com’);
header(‘Access-Control-Allow-Methods: GET, POST, PUT, DELETE’);
header(‘Access-Control-Allow-Headers: Authorization, Content-Type’);
});
`

Rate Limiting


Handle rate limit errors gracefully:
`javascript
if (response.status === 429) {
const resetTime = response.headers.get(‘X-RateLimit-Reset’);
// Wait until reset time before retrying
}
`

Resources


• WordPress REST API Handbook
• Application Passwords
• ShahiAssist API Reference (API.md)
• Postman Collection (available in plugin)