REST API
Use the REST API addon to integrate with web services and unleash the power of JReviews beyond your website.
Demo
Below you can see a little directory app that uses the API with our JReviews demo site. The app was developed using Ionic Vue.
We've made the source code available for free on Github. → Get the code. We are not providing support for building or integrating with existing mobile apps. The code is shared as is to be used as a reference.
Our demo refreshes periodically so if the app doesn't load, try waiting a bit and then re-load the page.
To sign-in to the app use:
- email: [email protected]
- password: demo
Getting Started
The first step to get started with the JReviews REST API is to create the JReviews REST API menu. This will be used as the base URL for all endpoints. For example, if the slug for the REST API menu is directory-api and you want to get a list of listings via the /jreviews/listings endpoint, the URL would be:
https://jreviews.com/directory-api/jreviews/listings
Authentication
Once you have a token, using it in the Authorization header for read-only requests allows obtaining user-specific information. For example:
• Permissions letting you know if the user can update, delete, or add media to an object.
• Information about whether a listing is in the user's favorites.
This is useful when building an app because it allows you to incorporate this information into the UI/UX without having to perform additional requests.
Create User Account
Register a new user account. This endpoint uses basic core Joomla and WordPress functionality for user registration.
Payload Parameters
Returns
If user accounts are automatically activated, the request returns a user object with Bearer token to use in Authorization header in subsequent requests. Otherwise a pending_activation status is returned.
In WordPress all accounts are automatically activated. In Joomla it depends on the site's configuration.
// Automatic activation
{
"id": 100,
"avatar": "",
"email": "",
"name": "",
"token": ""
}
// Pending activation
{
"status": "pending_activation",
"message": "User successfully registered. Needs to be activated using email activation link."
}
Connect User
Retrieve the user token to use in requests requiring authentication, and also non-authenticated requests that will provide more user-specific information like permissions.
Payload Parameters
{
"id": 100,
"avatar": "",
"email": "",
"name": "",
"token": ""
}
Logout User
Log out the user by invalidating the token.
Parameters
No parameters
{
"message": "Successfully logged out"
}
Listings
Create Listing
Create a listing.
Payload Parameters
{
"id": 123,
"title": "New Listing",
"slug": "new-listing",
"created": "2024-01-15 10:30:00",
"url": "https://example.com/listings/new-listing"
}
Get Listing
Get a single listing.
Parameters
No parameters
{
"id": 123,
"title": "Sample Listing",
"summary": "Listing description",
"fields": {},
"media": [],
"permissions": {
"can_edit": true,
"can_delete": false
}
}
Update Listing
Update a listing.
Payload Parameters
{
"id": 123,
"title": "Updated Listing",
"updated": "2024-01-15 11:00:00"
}
List Listings
Get a list of listings.
Parameters
No parameters
{
"data": [
{
"id": 123,
"title": "Listing 1"
},
{
"id": 124,
"title": "Listing 2"
}
],
"pagination": {
"total": 50,
"per_page": 10,
"current_page": 1
}
}
Delete Listing
Delete a listing.
Parameters
No parameters
{
"message": "Listing deleted successfully"
}
Comments
Create Comment
Create a listing comment which can include ratings if these are setup for the listing type.
Payload Parameters
{
"id": 456,
"comments": "Great place!",
"rating": 5,
"created": "2024-01-15 12:00:00"
}
Get Comment
Get a single comment.
Parameters
No parameters
{
"id": 456,
"comments": "Great place!",
"rating": 5,
"author": {
"id": 100,
"name": "John Doe"
},
"created": "2024-01-15 12:00:00",
"permissions": {
"can_edit": true,
"can_delete": false
}
}
Update Comment
Update a comment.
Payload Parameters
{
"id": 456,
"comments": "Updated comment!",
"rating": 4,
"updated": "2024-01-15 13:00:00"
}
List Comments
Get a list of comments.
Parameters
No parameters
{
"data": [
{
"id": 456,
"comments": "Great place!",
"rating": 5
},
{
"id": 457,
"comments": "Nice service",
"rating": 4
}
],
"pagination": {
"total": 100,
"per_page": 10,
"current_page": 1
}
}
List Listing Comments
Get a list of comments for a specific listing.
Parameters
No parameters
{
"data": [
{
"id": 456,
"comments": "Great place!",
"rating": 5,
"author": {
"id": 100,
"name": "John Doe"
},
"created": "2024-01-15 12:00:00"
}
],
"pagination": {
"total": 25,
"per_page": 10,
"current_page": 1
}
}
Delete Comment
Delete a comment.
Parameters
No parameters
{
"message": "Comment deleted successfully"
}
Media
Upload Photo to Listing
Only the listing owner is allowed to upload photos to the listing.
Payload Parameters
{
"id": 789,
"url": "https://example.com/media/photo.jpg",
"thumbnail": "https://example.com/media/photo-thumb.jpg"
}
Upload Attachment to Listing
Only the listing owner is allowed to upload attachments to the listing.
Payload Parameters
{
"id": 790,
"url": "https://example.com/media/document.pdf",
"filename": "document.pdf"
}
Delete Media
Delete a photo or attachment.
Parameters
No parameters
{
"message": "Media deleted successfully"
}
Listing Favorites
Favorite Listing
Parameters
No parameters
{
"message": "Listing added to favorites"
}
Unfavorite Listing
Parameters
No parameters
{
"message": "Listing removed from favorites"
}
Me
Get Authenticated User
Get the authenticated user information.
Parameters
No parameters
{
"id": 100,
"name": "John Doe",
"email": "[email protected]",
"avatar": "https://example.com/avatars/john.jpg"
}
Delete User Account
Delete the user's account.
Parameters
No parameters
{
"message": "User account deleted successfully"
}
Get Authenticated User Listings
Get list of listings submitted by the authenticated user.
Parameters
No parameters
{
"data": [
{
"id": 123,
"title": "My Listing",
"created": "2024-01-10 10:00:00"
}
],
"pagination": {
"total": 5,
"per_page": 10,
"current_page": 1
}
}
Get Authenticated User Favorites
Get list of favorites for the authenticated user.
Parameters
No parameters
{
"data": [
{
"id": 456,
"title": "Favorite Listing",
"created": "2024-01-12 14:30:00"
}
],
"pagination": {
"total": 12,
"per_page": 10,
"current_page": 1
}
}
Users
Get User Profile
Get a user's public profile.
Parameters
No parameters
{
"id": 100,
"name": "John Doe",
"avatar": "https://example.com/avatars/john.jpg",
"listings_count": 15
}
Field Options
Get Field Options
Get a complete list of options for a given field.
Parameters
No parameters
{
"field": "category",
"options": [
{"value": "1", "text": "Option 1"},
{"value": "2", "text": "Option 2"}
]
}
Search Field Options
Search a field's options.
Payload Parameters
{
"field": "category",
"results": [
{"value": "1", "text": "Matching Option"}
]
}
API Limitations
Only the documented endpoints are currently supported. JReviews has a very large number of features developed over 15 years. This means it will be difficult for the API to reach feature parity anytime soon.
At this time many existing website settings and functionality are not connected to the API. For example, the following is a small subset of features/implementations that are not-functional in the API:
- Automated titles generated when creating a listing
- Video and audio uploads
- Email notifications
- Hooks
- Guest submissions
- Custom field PHP output formatting