{"id":30546422,"url":"https://github.com/samsk/nextcloud_api_ext","last_synced_at":"2026-04-18T10:37:56.560Z","repository":{"id":310483124,"uuid":"1038618732","full_name":"samsk/nextcloud_api_ext","owner":"samsk","description":"Nextcloud Extended API","archived":false,"fork":false,"pushed_at":"2025-08-19T07:53:39.000Z","size":90,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-28T07:53:23.158Z","etag":null,"topics":["api","api-rest","nextcloud","nextcloud-app"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samsk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-15T14:31:17.000Z","updated_at":"2025-08-26T16:58:30.000Z","dependencies_parsed_at":"2025-08-18T12:31:18.957Z","dependency_job_id":"e9c487b5-f040-48ad-bfe8-5761df34e135","html_url":"https://github.com/samsk/nextcloud_api_ext","commit_stats":null,"previous_names":["samsk/nextcloud_api_ext"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/samsk/nextcloud_api_ext","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsk%2Fnextcloud_api_ext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsk%2Fnextcloud_api_ext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsk%2Fnextcloud_api_ext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsk%2Fnextcloud_api_ext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samsk","download_url":"https://codeload.github.com/samsk/nextcloud_api_ext/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsk%2Fnextcloud_api_ext/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31966206,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","nextcloud","nextcloud-app"],"created_at":"2025-08-28T02:00:48.228Z","updated_at":"2026-04-18T10:37:56.541Z","avatar_url":"https://github.com/samsk.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nextcloud API Extension\n\nA Nextcloud app that extends the REST API to provide advanced search capabilities for user tables, including phone number search and comprehensive filtering options with dynamic field handling.\n\n## Features\n\n- **Advanced User Search**: Search users by name, email, phone number, address, website, organisation, and other fields\n- **Dynamic Field Handling**: Automatically handles all searchable fields from the database schema\n- **Phone Number Search**: Intelligent phone number normalization and partial matching\n- **Flexible Filtering**: Filter by groups, account status, and custom user data fields\n- **Security \u0026 Permissions**: Simple, secure access control through group membership\n- **Rate Limiting**: Built-in rate limiting to prevent abuse\n- **Caching**: Intelligent caching for improved performance\n- **API Documentation**: Built-in API documentation and testing tools\n\n## Requirements\n\n### For Production\n- Nextcloud 27-31 (supports Nextcloud 30+)\n- PHP 8.2-8.4\n- Database: MySQL 8.0+/PostgreSQL 14+/SQLite 3.8+\n- Redis 7+ (recommended for caching)\n\n### For Development (Docker)\n- Docker 24.0+\n- Docker Compose 2.20+\n- 4GB RAM minimum\n- 10GB free disk space\n\n## Installation\n\n### Manual Installation\n\n1. Clone or download this repository to your Nextcloud `apps` directory:\n   ```bash\n   cd /path/to/nextcloud/apps\n   git clone https://github.com/your-repo/nextcloud_api_ext.git\n   ```\n\n2. Install PHP dependencies:\n   ```bash\n   cd nextcloud_api_ext\n   composer install --no-dev\n   ```\n\n3. Enable the app through the Nextcloud admin interface:\n   - Go to Settings → Apps\n   - Find \"Nextcloud API Extension\" and click \"Enable\"\n\n### App Store Installation\napp\n1. Go to Settings → Apps in your Nextcloud instance\n2. Search for \"Nextcloud API Extension\"\n3. Click \"Install\" and then \"Enable\"\n\n## Configuration\n\nAccess to the API is controlled through group membership. There are no configurable settings - this is by design to ensure security and simplicity.\n\n## API Usage\n\n### Authentication and Permissions\n\nThe API requires authentication and proper permissions. Access is granted to users who are either:\n- Nextcloud administrators, or\n- Members of the 'api-ext' group\n\nThis permission system is hardcoded for security and cannot be changed through the admin interface. To grant a user access to the API:\n\n1. Create the 'api-ext' group in Nextcloud if it doesn't exist:\n   ```bash\n   sudo -u www-data php occ group:add api-ext\n   ```\n\n2. Add users to the group:\n   ```bash\n   sudo -u www-data php occ group:adduser api-ext username\n   ```\n\n### Endpoints\n\n#### Search Users\n```\nGET /apps/nextcloud_api_ext/api/v1/users/search\n```\n\n**Parameters:**\n- `query` (string): General search term across all searchable fields\n- `uid` (string): Search by user ID\n- `displayname` (string): Search by display name\n- `email` (string): Search by email address\n- `phone` (string): Search by phone number (supports normalization)\n- `address` (string): Search by address\n- `website` (string): Search by website URL\n- `organisation` (string): Search by organisation\n- `enabled` (boolean): Filter by account status (true/false)\n- `groups` (array): Filter by user groups\n- `limit` (int): Number of results per page (max 100, default 25)\n- `offset` (int): Pagination offset (default 0)\n- `sort` (string): Sort field (uid, displayname, email, phone, address, website, organisation)\n- `order` (string): Sort order (asc, desc)\n\n**Example:**\n```bash\ncurl -X GET \"https://your-nextcloud.com/apps/nextcloud_api_ext/api/v1/users/search?query=john\u0026phone=555\u0026enabled=true\u0026limit=10\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n**Response:**\n```json\n{\n  \"users\": [\n    {\n      \"uid\": \"john.doe\",\n      \"displayName\": \"John Doe\",\n      \"email\": \"john@example.com\",\n      \"phone\": \"+1-555-0123\",\n      \"address\": \"123 Main St\",\n      \"website\": \"https://example.com\",\n      \"organisation\": \"Example Corp\",\n      \"enabled\": true\n    }\n  ],\n  \"total\": 150,\n  \"limit\": 10,\n  \"offset\": 0\n}\n```\n\n#### Count Users\n```\nGET /apps/nextcloud_api_ext/api/v1/users/count\n```\n\nReturns the count of users matching search criteria without full user data.\n\n**Example:**\n```bash\ncurl -X GET \"https://your-nextcloud.com/apps/nextcloud_api_ext/api/v1/users/count?query=john\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n**Response:**\n```json\n{\n  \"count\": 5\n}\n```\n\n#### Get Available Fields\n```\nGET /apps/nextcloud_api_ext/api/v1/users/fields\n```\n\nReturns information about available searchable fields.\n\n**Example:**\n```bash\ncurl -X GET \"https://your-nextcloud.com/apps/nextcloud_api_ext/api/v1/users/fields\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n**Response:**\n```json\n{\n  \"fields\": {\n    \"uid\": {\n      \"type\": \"string\",\n      \"searchable\": true,\n      \"sortable\": true,\n      \"description\": \"User ID\",\n      \"source\": \"users\"\n    },\n    \"displayname\": {\n      \"type\": \"string\",\n      \"searchable\": true,\n      \"sortable\": true,\n      \"description\": \"Display name\",\n      \"source\": \"users\"\n    },\n    \"email\": {\n      \"type\": \"string\",\n      \"searchable\": true,\n      \"sortable\": true,\n      \"description\": \"Email address\",\n      \"source\": \"accounts_data\",\n      \"filter_name\": \"email\"\n    },\n    \"phone\": {\n      \"type\": \"string\",\n      \"searchable\": true,\n      \"sortable\": true,\n      \"description\": \"Phone number\",\n      \"source\": \"accounts_data\",\n      \"filter_name\": \"phone\"\n    },\n    \"address\": {\n      \"type\": \"string\",\n      \"searchable\": true,\n      \"sortable\": true,\n      \"description\": \"Address\",\n      \"source\": \"accounts_data\",\n      \"filter_name\": \"address\"\n    },\n    \"website\": {\n      \"type\": \"string\",\n      \"searchable\": true,\n      \"sortable\": true,\n      \"description\": \"Website URL\",\n      \"source\": \"accounts_data\",\n      \"filter_name\": \"website\"\n    },\n    \"organisation\": {\n      \"type\": \"string\",\n      \"searchable\": true,\n      \"sortable\": true,\n      \"description\": \"Organisation\",\n      \"source\": \"accounts_data\",\n      \"filter_name\": \"organisation\"\n    },\n    \"enabled\": {\n      \"type\": \"boolean\",\n      \"searchable\": true,\n      \"sortable\": false,\n      \"description\": \"Account status\",\n      \"source\": \"accounts_data\",\n      \"filter_name\": \"profile_enabled\"\n    },\n    \"groups\": {\n      \"type\": \"array\",\n      \"searchable\": true,\n      \"sortable\": false,\n      \"description\": \"User groups\",\n      \"source\": \"groups\"\n    }\n  }\n}\n```\n\n### Dynamic Field System\n\nThe API uses a dynamic field system that automatically handles all searchable fields:\n\n- **Field Sources**: Fields can come from different database tables (`users`, `accounts_data`, `groups`)\n- **Automatic Joins**: Database joins are created dynamically based on field definitions\n- **Type-Safe Filtering**: Different field types (string, boolean, array) are handled appropriately\n- **Extensible**: New fields can be added by updating the field definitions\n\n### Phone Number Search\n\nThe phone search functionality supports:\n\n- **Multiple Formats**: International, local, and formatted numbers\n- **Partial Matching**: Search by area code, last digits, etc.\n- **Normalization**: Automatic phone number cleaning and standardization\n- **Fuzzy Matching**: Find similar numbers\n\n**Examples:**\n```bash\n# Search by international format\n?phone=+1-555-0123\n\n# Search by local format\n?phone=5550123\n\n# Search by partial number\n?phone=0123\n```\n\n## Development\n\n### Docker Development Environment (Recommended)\n\nThe easiest way to develop and test the app is using the provided Docker environment with Make. The environment uses Docker Compose V2 (note: uses `docker compose`, not `docker-compose`):\n\n1. **Start the development environment:**\n   ```bash\n   make start\n   ```\n\n2. **Access Nextcloud:**\n   - URL: http://localhost:8080\n   - Admin: admin / admin_password\n   - Database: nextcloud / nextcloud_password\n   - Redis: Running on default port (6379)\n\n3. **Run all tests:**\n   ```bash\n   make test-all\n   ```\n\n4. **View logs:**\n   ```bash\n   make logs                    # All services\n   make logs SERVICE=nextcloud  # Specific service\n   ```\n\n5. **Access container shell:**\n   ```bash\n   make shell                   # Nextcloud container\n   make shell-db               # Database container\n   make shell-redis            # Redis container\n   ```\n\n6. **Stop the environment:**\n   ```bash\n   make stop\n   ```\n\n**Available Make Commands:**\n- `make help` - Show all available commands\n- `make start` - Start the environment\n- `make stop` - Stop the environment\n- `make restart` - Restart the environment\n- `make up` - Start containers in detached mode\n- `make down` - Stop and remove containers\n- `make ps` - Show container status\n- `make logs [SERVICE=name]` - Show logs\n- `make test` - Run PHP unit tests\n- `make test-all` - Run all environment tests\n- `make install` - Install dependencies\n- `make shell [SERVICE=name]` - Open shell\n- `make clean` - Clean everything\n- `make status` - Show status\n- `make dev` - Start environment and run all tests\n- `make setup` - Complete setup (build, start, install)\n- `make reset` - Reset everything and start fresh\n- `make db-backup` - Create database backup\n- `make db-restore FILE=backup.sql` - Restore database\n- `make info` - Show environment information\n- `make health` - Check environment health\n\n### Manual Development Setup\n\nIf you prefer to develop without Docker:\n\n1. Clone the repository\n2. Install dependencies:\n   ```bash\n   composer install\n   ```\n\n3. Run tests:\n   ```bash\n   composer test\n   ```\n\n### Project Structure\n\n```\nnextcloud_api_ext/\n├── appinfo/                 # App metadata and routing\n├── lib/                     # PHP source code\n│   ├── Controller/         # API controllers\n│   ├── Service/           # Business logic\n│   ├── Db/               # Database layer\n│   └── AppInfo/          # App bootstrap\n├── tests/                # Unit and integration tests\n├── docker/               # Docker configuration files\n│   ├── nginx.conf        # Nginx configuration\n│   ├── php.ini           # PHP configuration\n│   ├── supervisord.conf  # Process management\n│   └── docker-dev.sh     # Docker development script\n├── .data/                # Container data (created by Docker)\n├── Makefile              # Development commands\n├── docker-compose.yml    # Docker environment\n└── composer.json         # PHP dependencies\n```\n\n### Development Commands\n\nThe project includes a comprehensive Makefile for easy development:\n\n```bash\n# Show all available commands\nmake help\n\n# Quick start\nmake dev                    # Start environment and run all tests\nmake setup                  # Complete setup (build, start, install)\n\n# Environment management\nmake start                  # Start development environment\nmake stop                   # Stop environment\nmake restart                # Restart environment\nmake reset                  # Reset everything and start fresh\n\n# Testing\nmake test-all               # Run all tests (environment + unit tests)\nmake test                   # Run PHP unit tests only\nmake health                 # Check environment health\n\n# Development\nmake shell                  # Access Nextcloud container\nmake shell-db              # Access database container\nmake logs SERVICE=nextcloud # View specific service logs\n\n# Database\nmake db-backup              # Create database backup\nmake db-restore FILE=backup.sql # Restore database\n```\n\n### Adding New Features\n\n1. Create feature branch\n2. Implement changes following Nextcloud coding standards\n3. Add tests for new functionality\n4. Update documentation\n5. Submit pull request\n\n## Security\n\n### Access Control\n\n- Access granted to administrators and 'api-ext' group members\n- Simple, secure permission model\n- No configurable permissions (for security)\n- Rate limiting to prevent abuse\n\n### Data Protection\n\n- Respects user privacy settings\n- GDPR-compliant data handling\n- Audit logging for security monitoring\n- Field-level access control\n\n### Best Practices\n\n- Always validate input parameters\n- Use prepared statements for database queries\n- Implement proper error handling\n- Log security events\n- Regular security updates\n\n## Troubleshooting\n\n### Common Issues\n\n1. **API returns 403 Forbidden**\n   - Check if user is an administrator or member of the 'api-ext' group\n   - Verify API is enabled in admin settings\n   - Check rate limiting settings\n   - Run `sudo -u www-data php occ group:list` to verify the 'api-ext' group exists\n   - Run `sudo -u www-data php occ user:info username` to check user's group membership\n\n2. **Phone search not working**\n   - Ensure phone search is enabled in settings\n   - Check if phone numbers are stored in user preferences\n   - Verify phone number format\n\n3. **Performance issues**\n   - Check database indexing\n   - Monitor cache performance\n   - Adjust rate limiting settings\n\n### Logs\n\nCheck Nextcloud logs for detailed error information:\n```bash\ntail -f /var/log/nextcloud/nextcloud.log\n```\n\n### Support\n\nFor issues and questions:\n1. Check the troubleshooting section\n2. Review the logs\n3. Create an issue on GitHub\n4. Contact the development team\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\n### Version 1.3.0 (Latest)\n- **Dynamic Field System**: Implemented dynamic field handling for all searchable fields\n- **Enhanced Search**: Added support for address, website, organisation fields\n- **Improved Filtering**: Better boolean field handling and type-safe parameter parsing\n- **Code Refactoring**: Eliminated code duplication with dynamic query building\n- **Removed Fields**: Removed twitter and lastLogin fields from search and responses\n- **API Improvements**: More robust parameter parsing and error handling\n\n### Version 1.2.0\n- **Nextcloud 30+ Compatibility**: Updated to support Nextcloud 27-31\n- **PHP 8.2+ Support**: Updated minimum PHP requirement to 8.2, supports up to PHP 8.4\n- **Updated Dependencies**: Upgraded to Doctrine DBAL ^4.0 and PHPUnit ^11.0\n- **Future-Ready**: Compatible with Nextcloud 30 and 31\n\n### Version 1.1.0\n- Updated to support Nextcloud 27+\n- Added Redis 7 support for improved caching\n- Enhanced security features\n- Performance improvements\n- Bug fixes and stability improvements\n\n### Version 1.0.0\n- Initial release\n- Basic user search functionality\n- Phone number search\n- Admin configuration interface\n- Security and permission system\n- Rate limiting\n- Caching support\n\n## Acknowledgments\n\n- Nextcloud community for the excellent platform\n- Contributors and testers\n- Open source community for inspiration and tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsk%2Fnextcloud_api_ext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamsk%2Fnextcloud_api_ext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsk%2Fnextcloud_api_ext/lists"}