Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Codeinwp/yourls-api-list-extended?tab=readme-ov-file
YOURLS API List action with sorting, pagination, total count, and field selection.
https://github.com/Codeinwp/yourls-api-list-extended?tab=readme-ov-file
yourls yourls-api yourls-extension yourls-plugin
Last synced: about 19 hours ago
JSON representation
YOURLS API List action with sorting, pagination, total count, and field selection.
- Host: GitHub
- URL: https://github.com/Codeinwp/yourls-api-list-extended?tab=readme-ov-file
- Owner: Codeinwp
- Created: 2024-09-16T06:22:50.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-10-24T23:34:36.000Z (3 months ago)
- Last Synced: 2024-10-26T12:08:46.395Z (2 months ago)
- Topics: yourls, yourls-api, yourls-extension, yourls-plugin
- Language: PHP
- Homepage:
- Size: 2.93 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome - API List Extended - Add a "list" action to the API with advanced options, such as shorting, pagination and field selection. (Plugins / A)
README
# YOURLS API Action List Extended
**Plugin Name**: YOURLS API Action List Extended
**Version**: 1.0.0
**Author**: Hardeep Asrani
**Author URI**: [https://themeisle.com](https://themeisle.com)
**Plugin URI**: [https://github.com/Codeinwp/yourls-api-list-extended](https://github.com/Codeinwp/yourls-api-list-extended)
**Description**: YOURLS API List action with sorting, pagination, total count, and field selection.
## Description
This plugin extends the YOURLS API by adding a `list` action with advanced capabilities. It allows users to retrieve a list of shortened URLs with options for:
- Sorting by keyword, URL, title, timestamp, IP address, or clicks.
- Pagination using offset and limit (per page).
- Custom selection of fields to be returned in the API response.
- Searching by keyword.
- Total count of links to assist with pagination.
## Features
- **Sorting**: Sort results by any valid field (`keyword`, `url`, `title`, `timestamp`, `ip`, `clicks`).
- **Pagination**: Use the `offset` and `perpage` parameters to paginate results.
- **Field Selection**: Select specific fields to return (e.g., `keyword`, `url`, `clicks`). By default, all fields are returned.
- **Search**: Search for links by keyword.
- **Total Count**: Returns the total number of links in the database, useful for pagination.
## Installation
1. Download and extract the plugin.
2. Upload the plugin folder to your YOURLS `user/plugins/` directory.
3. Activate the plugin from the YOURLS admin interface.
4. The plugin will automatically extend the YOURLS API with the new `list` action.
## API Usage
### Base URL
Use the following base URL for API requests:
```
http:///yourls-api.php
```
### Required Parameters
- `signature`: Your YOURLS API signature token.
- `action`: Must be set to `list`.
- `format`: Optional. Specify `json` for JSON responses (default).
### Optional Parameters
- `sortby`: Field to sort by (`keyword`, `url`, `title`, `timestamp`, `ip`, `clicks`). Default is `timestamp`.
- `sortorder`: Sort order, either `ASC` (ascending) or `DESC` (descending). Default is `DESC`.
- `offset`: Number of links to skip (used for pagination). Default is `0`.
- `perpage`: Number of links to return per page. Default is `50`.
- `query`: Search query to filter results by keyword.
- `fields[]`: An array of fields to return (e.g., `fields[]=keyword&fields[]=url`). Default is all fields (`*`).
### Example Request
```
GET http:///yourls-api.php?action=list&signature=your_signature&sortby=clicks&sortorder=ASC&offset=0&perpage=10&fields[]=keyword&fields[]=url
```
This example retrieves the first 10 results, sorted by clicks in ascending order, and returns only the `keyword` and `url` fields.
### Example Response
```json
{
"statusCode": 200,
"message": "success",
"result": [
{
"keyword": "example1",
"url": "http://example.com"
},
{
"keyword": "example2",
"url": "http://example.org"
}
],
"total": 100,
"offset": 0,
"perpage": 10
}
```
## Parameters Overview
| Parameter | Type | Description | Default |
|------------|--------|-----------------------------------------------------------------------------|---------------|
| `sortby` | string | Field to sort results by (`keyword`, `url`, `title`, `ip`, `timestamp`, `clicks`). | `timestamp` |
| `sortorder`| string | Sort order, `ASC` for ascending, `DESC` for descending. | `DESC` |
| `offset` | int | Offset for pagination, number of links to skip. | `0` |
| `perpage` | int | Number of links to return per page. | `50` |
| `query` | string | Search query to filter results by keyword. | |
| `fields[]` | array | Fields to return in the response. Use array format: `fields[]=keyword`. | `*` (all) |
## License
This plugin is released under the MIT License.