# Developer Guide - LDAP-Rest

Welcome to the LDAP-Rest Developer Guide! This guide helps you build web applications using LDAP-Rest's APIs and libraries.

## Quick Links

### 🚀 Getting Started

- [Introduction & Architecture](#introduction)
- [Quick Start Guide](#quick-start)

### 📚 Core Documentation

- **[REST API Documentation](./api/rest-api.md)** - Complete API reference (Config, Users, Groups, Organizations)
- **[Browser Libraries](./browser/libraries.md)** - LdapTreeViewer and LdapUserEditor
- **[JSON Schemas](./schemas/README.md)** - Schema structure and validation
- **[Integration Examples](./examples/README.md)** - React, Vue.js, Vanilla JavaScript examples
- **[Plugin Development](../plugin-development/README.md)** - Create your own plugins

### 🔧 Reference

- **[API Reference](./api/reference.md)** - Complete API reference with all endpoints
- [Authentication](./api/rest-api.md#authentication) - OpenID, Token, LemonLDAP::NG
- [Troubleshooting](./api/reference.md#troubleshooting) - Common issues and solutions

---

## Introduction

LDAP-Rest is a lightweight LDAP directory manager that provides:

- **Complete REST API** for managing LDAP users, groups, and organizations
- **Ready-to-use browser libraries** in JavaScript/TypeScript
- **Schema-driven architecture** to adapt to different directory types (Twake, Active Directory, standard LDAP)
- **Dynamic configuration** exposed via API
- **Plugin-based extensibility** for custom functionality
- **Robust error handling** ensuring server stability even when plugins encounter errors

### Architecture Overview

```
┌─────────────────────────────────────┐
│   Your Web Application              │
│                                     │
│  ┌───────────────────────────────┐ │
│  │  Browser Libraries            │ │
│  │  - LdapTreeViewer             │ │
│  │  - LdapUserEditor             │ │
│  └───────────────────────────────┘ │
│              ↓ HTTP                 │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   LDAP-Rest Server                    │
│                                     │
│  ┌───────────────────────────────┐ │
│  │  REST API                     │ │
│  │  - /api/v1/config             │ │
│  │  - /api/v1/ldap/users         │ │
│  │  - /api/v1/ldap/groups        │ │
│  │  - /api/v1/ldap/organizations │ │
│  └───────────────────────────────┘ │
│              ↓                      │
│  ┌───────────────────────────────┐ │
│  │  Plugins                      │ │
│  │  - configApi                  │ │
│  │  - ldapFlatGeneric            │ │
│  │  - ldapGroups                 │ │
│  │  - ldapOrganizations          │ │
│  └───────────────────────────────┘ │
│              ↓                      │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│   LDAP Directory Server             │
│   (OpenLDAP, AD, 389 Directory...)  │
└─────────────────────────────────────┘
```

---

## Quick Start

### 1. Start LDAP-Rest Server

```bash
npx ldap-rest \
  --ldap-base 'dc=example,dc=com' \
  --ldap-url 'ldap://localhost:389' \
  --ldap-dn 'cn=admin,dc=example,dc=com' \
  --ldap-pwd 'admin' \
  --plugin core/configApi \
  --plugin core/ldap/flatGeneric \
  --ldap-flat-schema ./static/schemas/standard/users.json \
  --plugin core/static \
  --static-path ./static
```

### 2. Access the Configuration API

```javascript
const config = await fetch('http://localhost:8081/api/v1/config').then(r =>
  r.json()
);

console.log(config);
// {
//   "apiPrefix": "/api",
//   "ldapBase": "dc=example,dc=com",
//   "features": { ... }
// }
```

### 3. Use the Browser Libraries

```html
<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="/static/browser/ldap-user-editor.css" />
    <link
      href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"
      rel="stylesheet"
    />
    <link
      href="https://fonts.googleapis.com/icon?family=Material+Icons"
      rel="stylesheet"
    />
  </head>
  <body>
    <div id="editor"></div>

    <script src="/static/browser/ldap-user-editor.js"></script>
    <script>
      const { LdapUserEditor } = window.LdapUserEditor;

      const editor = new LdapUserEditor({
        containerId: 'editor',
        apiBaseUrl: window.location.origin,
        onUserSaved: dn => console.log('Saved:', dn),
      });

      editor.init();
    </script>
  </body>
</html>
```

---

## Documentation Structure

### API Documentation

- **[REST API Guide](./api/rest-api.md)**
  - Configuration API
  - Organizations API
  - Users API
  - Groups API
  - Authentication

- **[Complete API Reference](./api/reference.md)**
  - All endpoints with examples
  - Request/response formats
  - Error codes
  - LDAP modify format

### Browser Libraries

- **[Browser Libraries Guide](./browser/libraries.md)**
  - LdapTreeViewer - Interactive LDAP tree
  - LdapUserEditor - Complete user editor
  - Configuration options
  - API methods
  - Customization

### Schemas

- **[JSON Schemas Guide](./schemas/README.md)**
  - Schema structure
  - Entity metadata
  - Attribute types
  - Semantic roles
  - Validation rules
  - Predefined schemas

### Integration

- **[Integration Examples](./examples/README.md)**
  - React application
  - Vue.js application
  - Vanilla JavaScript
  - Group management
  - Custom components

### Plugin Development

- **[Plugin Development Guide](../plugin-development/README.md)**
  - Creating plugins
  - Custom configuration
  - Hooks system
  - LDAP operations
  - API endpoints
  - Testing

---

## Key Concepts

### Schema-Driven Architecture

LDAP-Rest uses JSON schemas to define LDAP entity structure:

```json
{
  "entity": {
    "name": "users",
    "mainAttribute": "uid",
    "objectClass": ["top", "person", "inetOrgPerson"],
    "base": "ou=users,{ldap_base}"
  },
  "attributes": {
    "uid": {
      "type": "string",
      "required": true,
      "role": "identifier"
    },
    "cn": {
      "type": "string",
      "required": true,
      "role": "displayName"
    }
  }
}
```

See [JSON Schemas Guide](./schemas/README.md) for details.

### Dynamic Configuration

The `/api/v1/config` endpoint exposes all available features, endpoints, and schemas. Your application discovers capabilities at runtime:

```javascript
const config = await fetch('/api/v1/config').then(r => r.json());

// Find users endpoint
const usersEndpoint = config.features.ldapFlatGeneric.flatResources.find(
  r => r.pluralName === 'users'
)?.endpoints.list;

// Use it
const users = await fetch(usersEndpoint).then(r => r.json());
```

See [REST API Guide](./api/rest-api.md) for details.

### Plugin-Based Extensibility

Extend LDAP-Rest with custom plugins that:

- Add REST API endpoints
- Hook into LDAP operations
- Integrate external systems
- Implement custom logic

See [Plugin Development Guide](../plugin-development/README.md) for details.

---

## Next Steps

1. **Learn the API** - Read the [REST API Guide](./api/rest-api.md)
2. **Try the Libraries** - Check the [Browser Libraries Guide](./browser/libraries.md)
3. **See Examples** - Explore [Integration Examples](./examples/README.md)
4. **Build a Plugin** - Follow the [Plugin Development Guide](../plugin-development/README.md)

---

## Resources

- [GitHub Repository](https://github.com/linagora/ldap-rest)
- [Contributing Guide](../../CONTRIBUTING.md)
- [Plugin Development](../plugin-development/README.md)
- [Hooks Reference](../plugin-development/hooks.md)

---

## Support

- **Issues**: https://github.com/linagora/ldap-rest/issues
- **Documentation**: https://github.com/linagora/ldap-rest/tree/master/docs

---

## License

[![Powered by LINAGORA](./linagora.png)](https://linagora.com)

[AGPL-3.0](../LICENSE) - Copyright 2025-present LINAGORA
