strapi-plugin-api-select
Version:
A powerful Strapi v5 plugin that provides API-driven select fields with support for GET/POST requests, custom headers, flexible response mapping, and multilingual content.
267 lines (194 loc) • 6.24 kB
Markdown
# Strapi Plugin API Select
[](https://badge.fury.io/js/strapi-plugin-api-select)
[](https://npmjs.org/package/strapi-plugin-api-select)
[](https://opensource.org/licenses/MIT)
A powerful **Strapi v5 plugin** that provides API-driven select fields with support for GET/POST requests, custom headers, flexible response mapping, and multilingual content.
## ✨ Features
- 🔗 **External API Integration** - Fetch select options from any REST API
- 📡 **HTTP Methods** - Support for both GET and POST requests
- 🔐 **Authentication** - Custom headers and API token support
- 📋 **Request Payloads** - Configure JSON payloads for POST requests
- 🗺️ **Flexible Mapping** - Handle diverse API response structures
- 🌐 **Proxy Mode** - Built-in proxy for private APIs and CORS bypass
- 🌍 **Multilingual** - Works with Strapi's i18n features
- 📱 **Selection Modes** - Single or multiple selection
- ⚡ **Performance** - Optimized with error handling and caching
## 🚀 Installation
```bash
npm install strapi-plugin-api-select
```
## ⚙️ Configuration
Add the plugin to your `config/plugins.js` file:
```javascript
module.exports = {
// ...
"api-select": {
enabled: true,
},
// ...
};
```
## 📖 Usage
### 1. Add Field to Content Type
1. Go to **Content-Type Builder** in your Strapi admin
2. Select your content type (e.g., Article, Product)
3. Click **Add another field**
4. Choose **Custom** → **API Select**
5. Configure your field options
### 2. Field Configuration
#### Basic Settings
- **Options API URL**: The endpoint that returns your options
- **Label Key**: Field to use for display text (default: `name`)
- **Value Key**: Field to use for stored value (default: `id`)
- **Select Mode**: Single or Multiple selection
- **Auth Mode**: Public API or Proxy for private APIs
#### Advanced Settings
- **HTTP Method**: GET or POST (default: `GET`)
- **Request Payload**: JSON payload for POST requests
- **Custom Headers**: Additional headers as JSON object
- **Response Data Path**: Path to array in response (e.g., `data`, `results`)
- **Response Mapping**: Custom field mapping for complex responses
## 📋 Examples
### Basic GET Request
```javascript
// API URL: https://api.example.com/categories
// Response:
[
{ id: 1, name: "Technology" },
{ id: 2, name: "Science" },
];
// Configuration:
// - Label Key: name
// - Value Key: id
```
### POST Request with Payload
```javascript
// Configuration:
// - HTTP Method: POST
// - Request Payload:
{
"filters": {"status": "active"},
"limit": 100
}
// - Custom Headers:
{
"Authorization": "Bearer your-token",
"X-API-Key": "your-api-key"
}
```
### Complex Response Mapping
```javascript
// API Response:
{
"success": true,
"data": {
"users": [
{
"userId": 1,
"profile": {"displayName": "John Doe"},
"department": {"name": "Engineering"}
}
]
}
}
// Configuration:
// - Response Data Path: data.users
// - Response Mapping:
{
"value": "userId",
"label": "profile.displayName",
"group": "department.name"
}
```
### Different Response Formats
The plugin automatically handles various API response structures:
#### Direct Array
```json
[
{ "id": 1, "name": "Option 1" },
{ "id": 2, "name": "Option 2" }
]
```
#### Nested Data
```json
{
"data": [
{ "id": 1, "title": "Option 1" },
{ "id": 2, "title": "Option 2" }
]
}
```
#### Complex Structure
```json
{
"response": {
"items": [{ "uuid": "abc-123", "label": "Custom Option" }]
}
}
```
## 🔒 Security Features
- **SSRF Protection**: Validates API URLs to prevent server-side request forgery
- **Proxy Mode**: Routes requests through Strapi backend for private APIs
- **Environment Variables**: Support for API tokens via environment variables
Set your API token:
```bash
CUSTOM_STRAPI_SELECT_TOKEN=your_api_token_here
```
## 🌐 Proxy Mode
For private APIs or to bypass CORS issues, use proxy mode:
1. Set **Auth Mode** to "Proxy"
2. Requests will be routed through your Strapi backend
3. Configure authentication via environment variables
## 🎛️ Field Types Supported
### Single Selection
Returns a single value:
```javascript
"selected_option_id";
```
### Multiple Selection
Returns an array of values:
```javascript
["option_1", "option_2", "option_3"];
```
## 🔧 Development
### Local Development
1. Clone the repository
2. Install dependencies: `npm install`
3. Link locally: `npm link`
4. In your Strapi project: `npm link strapi-plugin-api-select`
5. Restart Strapi
### Testing
```bash
npm test
```
## 📄 API Reference
### Server Routes
- `GET /api/api-select/fetch` - Proxy endpoint for fetching external API data
### Query Parameters
- `api` - External API URL
- `labelKey` - Field name for option labels
- `valueKey` - Field name for option values
- `method` - HTTP method (GET/POST)
- `payload` - JSON payload for POST requests
- `headers` - Custom headers as JSON string
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request
## 📝 Changelog
See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- 📖 [Documentation](https://github.com/ManojNathIC/strapi-plugin-api-select#readme)
- 🐛 [Issue Tracker](https://github.com/ManojNathIC/strapi-plugin-api-select/issues)
- 💬 [Strapi Discord](https://discord.strapi.io) - Ask in #plugins channel
## 🙏 Acknowledgments
- Built for [Strapi v5](https://strapi.io)
- Inspired by the need for dynamic content in headless CMS
- Thanks to the Strapi community for feedback and contributions
---
Made with ❤️ for the Strapi community