Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/samsk/nextcloud_api_ext

Nextcloud Extended API
https://github.com/samsk/nextcloud_api_ext

api api-rest nextcloud nextcloud-app

Last synced: 2 months ago
JSON representation

Nextcloud Extended API

Awesome Lists containing this project

README 

          
# Nextcloud API Extension



A 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.



## Features



- **Advanced User Search**: Search users by name, email, phone number, address, website, organisation, and other fields

- **Dynamic Field Handling**: Automatically handles all searchable fields from the database schema

- **Phone Number Search**: Intelligent phone number normalization and partial matching

- **Flexible Filtering**: Filter by groups, account status, and custom user data fields

- **Security & Permissions**: Simple, secure access control through group membership

- **Rate Limiting**: Built-in rate limiting to prevent abuse

- **Caching**: Intelligent caching for improved performance

- **API Documentation**: Built-in API documentation and testing tools



## Requirements



### For Production

- Nextcloud 27-31 (supports Nextcloud 30+)

- PHP 8.2-8.4

- Database: MySQL 8.0+/PostgreSQL 14+/SQLite 3.8+

- Redis 7+ (recommended for caching)



### For Development (Docker)

- Docker 24.0+

- Docker Compose 2.20+

- 4GB RAM minimum

- 10GB free disk space



## Installation



### Manual Installation



1. Clone or download this repository to your Nextcloud `apps` directory:

   ```bash

   cd /path/to/nextcloud/apps

   git clone https://github.com/your-repo/nextcloud_api_ext.git

   ```



2. Install PHP dependencies:

   ```bash

   cd nextcloud_api_ext

   composer install --no-dev

   ```



3. Enable the app through the Nextcloud admin interface:

   - Go to Settings → Apps

   - Find "Nextcloud API Extension" and click "Enable"



### App Store Installation

app

1. Go to Settings → Apps in your Nextcloud instance

2. Search for "Nextcloud API Extension"

3. Click "Install" and then "Enable"



## Configuration



Access to the API is controlled through group membership. There are no configurable settings - this is by design to ensure security and simplicity.



## API Usage



### Authentication and Permissions



The API requires authentication and proper permissions. Access is granted to users who are either:

- Nextcloud administrators, or

- Members of the 'api-ext' group



This permission system is hardcoded for security and cannot be changed through the admin interface. To grant a user access to the API:



1. Create the 'api-ext' group in Nextcloud if it doesn't exist:

   ```bash

   sudo -u www-data php occ group:add api-ext

   ```



2. Add users to the group:

   ```bash

   sudo -u www-data php occ group:adduser api-ext username

   ```



### Endpoints



#### Search Users

```

GET /apps/nextcloud_api_ext/api/v1/users/search

```



**Parameters:**

- `query` (string): General search term across all searchable fields

- `uid` (string): Search by user ID

- `displayname` (string): Search by display name

- `email` (string): Search by email address

- `phone` (string): Search by phone number (supports normalization)

- `address` (string): Search by address

- `website` (string): Search by website URL

- `organisation` (string): Search by organisation

- `enabled` (boolean): Filter by account status (true/false)

- `groups` (array): Filter by user groups

- `limit` (int): Number of results per page (max 100, default 25)

- `offset` (int): Pagination offset (default 0)

- `sort` (string): Sort field (uid, displayname, email, phone, address, website, organisation)

- `order` (string): Sort order (asc, desc)



**Example:**

```bash

curl -X GET "https://your-nextcloud.com/apps/nextcloud_api_ext/api/v1/users/search?query=john&phone=555&enabled=true&limit=10" \

  -H "Authorization: Bearer YOUR_TOKEN"

```



**Response:**

```json

{

  "users": [

    {

      "uid": "john.doe",

      "displayName": "John Doe",

      "email": "john@example.com",

      "phone": "+1-555-0123",

      "address": "123 Main St",

      "website": "https://example.com",

      "organisation": "Example Corp",

      "enabled": true

    }

  ],

  "total": 150,

  "limit": 10,

  "offset": 0

}

```



#### Count Users

```

GET /apps/nextcloud_api_ext/api/v1/users/count

```



Returns the count of users matching search criteria without full user data.



**Example:**

```bash

curl -X GET "https://your-nextcloud.com/apps/nextcloud_api_ext/api/v1/users/count?query=john" \

  -H "Authorization: Bearer YOUR_TOKEN"

```



**Response:**

```json

{

  "count": 5

}

```



#### Get Available Fields

```

GET /apps/nextcloud_api_ext/api/v1/users/fields

```



Returns information about available searchable fields.



**Example:**

```bash

curl -X GET "https://your-nextcloud.com/apps/nextcloud_api_ext/api/v1/users/fields" \

  -H "Authorization: Bearer YOUR_TOKEN"

```



**Response:**

```json

{

  "fields": {

    "uid": {

      "type": "string",

      "searchable": true,

      "sortable": true,

      "description": "User ID",

      "source": "users"

    },

    "displayname": {

      "type": "string",

      "searchable": true,

      "sortable": true,

      "description": "Display name",

      "source": "users"

    },

    "email": {

      "type": "string",

      "searchable": true,

      "sortable": true,

      "description": "Email address",

      "source": "accounts_data",

      "filter_name": "email"

    },

    "phone": {

      "type": "string",

      "searchable": true,

      "sortable": true,

      "description": "Phone number",

      "source": "accounts_data",

      "filter_name": "phone"

    },

    "address": {

      "type": "string",

      "searchable": true,

      "sortable": true,

      "description": "Address",

      "source": "accounts_data",

      "filter_name": "address"

    },

    "website": {

      "type": "string",

      "searchable": true,

      "sortable": true,

      "description": "Website URL",

      "source": "accounts_data",

      "filter_name": "website"

    },

    "organisation": {

      "type": "string",

      "searchable": true,

      "sortable": true,

      "description": "Organisation",

      "source": "accounts_data",

      "filter_name": "organisation"

    },

    "enabled": {

      "type": "boolean",

      "searchable": true,

      "sortable": false,

      "description": "Account status",

      "source": "accounts_data",

      "filter_name": "profile_enabled"

    },

    "groups": {

      "type": "array",

      "searchable": true,

      "sortable": false,

      "description": "User groups",

      "source": "groups"

    }

  }

}

```



### Dynamic Field System



The API uses a dynamic field system that automatically handles all searchable fields:



- **Field Sources**: Fields can come from different database tables (`users`, `accounts_data`, `groups`)

- **Automatic Joins**: Database joins are created dynamically based on field definitions

- **Type-Safe Filtering**: Different field types (string, boolean, array) are handled appropriately

- **Extensible**: New fields can be added by updating the field definitions



### Phone Number Search



The phone search functionality supports:



- **Multiple Formats**: International, local, and formatted numbers

- **Partial Matching**: Search by area code, last digits, etc.

- **Normalization**: Automatic phone number cleaning and standardization

- **Fuzzy Matching**: Find similar numbers



**Examples:**

```bash

# Search by international format

?phone=+1-555-0123



# Search by local format

?phone=5550123



# Search by partial number

?phone=0123

```



## Development



### Docker Development Environment (Recommended)



The 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`):



1. **Start the development environment:**

   ```bash

   make start

   ```



2. **Access Nextcloud:**

   - URL: http://localhost:8080

   - Admin: admin / admin_password

   - Database: nextcloud / nextcloud_password

   - Redis: Running on default port (6379)



3. **Run all tests:**

   ```bash

   make test-all

   ```



4. **View logs:**

   ```bash

   make logs                    # All services

   make logs SERVICE=nextcloud  # Specific service

   ```



5. **Access container shell:**

   ```bash

   make shell                   # Nextcloud container

   make shell-db               # Database container

   make shell-redis            # Redis container

   ```



6. **Stop the environment:**

   ```bash

   make stop

   ```



**Available Make Commands:**

- `make help` - Show all available commands

- `make start` - Start the environment

- `make stop` - Stop the environment

- `make restart` - Restart the environment

- `make up` - Start containers in detached mode

- `make down` - Stop and remove containers

- `make ps` - Show container status

- `make logs [SERVICE=name]` - Show logs

- `make test` - Run PHP unit tests

- `make test-all` - Run all environment tests

- `make install` - Install dependencies

- `make shell [SERVICE=name]` - Open shell

- `make clean` - Clean everything

- `make status` - Show status

- `make dev` - Start environment and run all tests

- `make setup` - Complete setup (build, start, install)

- `make reset` - Reset everything and start fresh

- `make db-backup` - Create database backup

- `make db-restore FILE=backup.sql` - Restore database

- `make info` - Show environment information

- `make health` - Check environment health



### Manual Development Setup



If you prefer to develop without Docker:



1. Clone the repository

2. Install dependencies:

   ```bash

   composer install

   ```



3. Run tests:

   ```bash

   composer test

   ```



### Project Structure



```

nextcloud_api_ext/

├── appinfo/                 # App metadata and routing

├── lib/                     # PHP source code

│   ├── Controller/         # API controllers

│   ├── Service/           # Business logic

│   ├── Db/               # Database layer

│   └── AppInfo/          # App bootstrap

├── tests/                # Unit and integration tests

├── docker/               # Docker configuration files

│   ├── nginx.conf        # Nginx configuration

│   ├── php.ini           # PHP configuration

│   ├── supervisord.conf  # Process management

│   └── docker-dev.sh     # Docker development script

├── .data/                # Container data (created by Docker)

├── Makefile              # Development commands

├── docker-compose.yml    # Docker environment

└── composer.json         # PHP dependencies

```



### Development Commands



The project includes a comprehensive Makefile for easy development:



```bash

# Show all available commands

make help



# Quick start

make dev                    # Start environment and run all tests

make setup                  # Complete setup (build, start, install)



# Environment management

make start                  # Start development environment

make stop                   # Stop environment

make restart                # Restart environment

make reset                  # Reset everything and start fresh



# Testing

make test-all               # Run all tests (environment + unit tests)

make test                   # Run PHP unit tests only

make health                 # Check environment health



# Development

make shell                  # Access Nextcloud container

make shell-db              # Access database container

make logs SERVICE=nextcloud # View specific service logs



# Database

make db-backup              # Create database backup

make db-restore FILE=backup.sql # Restore database

```



### Adding New Features



1. Create feature branch

2. Implement changes following Nextcloud coding standards

3. Add tests for new functionality

4. Update documentation

5. Submit pull request



## Security



### Access Control



- Access granted to administrators and 'api-ext' group members

- Simple, secure permission model

- No configurable permissions (for security)

- Rate limiting to prevent abuse



### Data Protection



- Respects user privacy settings

- GDPR-compliant data handling

- Audit logging for security monitoring

- Field-level access control



### Best Practices



- Always validate input parameters

- Use prepared statements for database queries

- Implement proper error handling

- Log security events

- Regular security updates



## Troubleshooting



### Common Issues



1. **API returns 403 Forbidden**

   - Check if user is an administrator or member of the 'api-ext' group

   - Verify API is enabled in admin settings

   - Check rate limiting settings

   - Run `sudo -u www-data php occ group:list` to verify the 'api-ext' group exists

   - Run `sudo -u www-data php occ user:info username` to check user's group membership



2. **Phone search not working**

   - Ensure phone search is enabled in settings

   - Check if phone numbers are stored in user preferences

   - Verify phone number format



3. **Performance issues**

   - Check database indexing

   - Monitor cache performance

   - Adjust rate limiting settings



### Logs



Check Nextcloud logs for detailed error information:

```bash

tail -f /var/log/nextcloud/nextcloud.log

```



### Support



For issues and questions:

1. Check the troubleshooting section

2. Review the logs

3. Create an issue on GitHub

4. Contact the development team



## Contributing



We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.



## License



This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.



## Changelog



### Version 1.3.0 (Latest)

- **Dynamic Field System**: Implemented dynamic field handling for all searchable fields

- **Enhanced Search**: Added support for address, website, organisation fields

- **Improved Filtering**: Better boolean field handling and type-safe parameter parsing

- **Code Refactoring**: Eliminated code duplication with dynamic query building

- **Removed Fields**: Removed twitter and lastLogin fields from search and responses

- **API Improvements**: More robust parameter parsing and error handling



### Version 1.2.0

- **Nextcloud 30+ Compatibility**: Updated to support Nextcloud 27-31

- **PHP 8.2+ Support**: Updated minimum PHP requirement to 8.2, supports up to PHP 8.4

- **Updated Dependencies**: Upgraded to Doctrine DBAL ^4.0 and PHPUnit ^11.0

- **Future-Ready**: Compatible with Nextcloud 30 and 31



### Version 1.1.0

- Updated to support Nextcloud 27+

- Added Redis 7 support for improved caching

- Enhanced security features

- Performance improvements

- Bug fixes and stability improvements



### Version 1.0.0

- Initial release

- Basic user search functionality

- Phone number search

- Admin configuration interface

- Security and permission system

- Rate limiting

- Caching support



## Acknowledgments



- Nextcloud community for the excellent platform

- Contributors and testers

- Open source community for inspiration and tools